> For the complete documentation index, see [llms.txt](https://rosemary-2.gitbook.io/rosemary-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://rosemary-2.gitbook.io/rosemary-docs/readme.md).

# Rosemary

Rosemary is a cross-platform transparent network tunneling platform. It deploys lightweight agents on remote hosts and uses kernel-level traffic interception on the server so that all traffic to the agent's subnets is transparently routed through the agent. No TUN/TAP device, no proxy settings, no proxychains required.

**Author:** Chokri Hammedi (blue0x1) **License:** GPLv3 **Language:** Go 1.25

***

## How It Works

```
Remote Host                        Server (runs as root)
+-------------------+             +----------------------------+
| Agent (no root)   |  QUIC/UDP   | Agent transport :2048/udp  |
|                   +<----------->+ HTTP + REST API  :1024     |
| - subnet discovery| AES-256-GCM | TCP proxy        :1080     |
| - TCP forwarding  | RTN frames  | UDP TPROXY       :1081     |
| - UDP forwarding  |             | DNS proxy        :5300     |
| - DNS resolution  |             | ICMP interceptor           |
| - ping sweep      |             | iptables / WinDivert       |
| - port scan       |             | Web Dashboard              |
+-------------------+             +----------------------------+
```

The server installs kernel-level interception rules for the agent subnets. Once an agent connects, any traffic your machine sends to those subnets is automatically tunneled through the agent with no configuration on the client side.

***

## Install

```bash
go install github.com/blue0x1/rosemary/rosemary@latest
go install github.com/blue0x1/rosemary/agent@latest
```

Or download pre-built binaries from the [Releases](https://github.com/blue0x1/rosemary/releases) page.

***

## Pages

| Page             | Description                                                    |
| ---------------- | -------------------------------------------------------------- |
| Getting Started  | Installation, first agent, config examples                     |
| Architecture     | QUIC transport, bind mode, OS-level interception               |
| Agent            | Modes, CLI flags, Invoke-Rosemary, subnet discovery, reconnect |
| Server           | Proxy listeners, iptables rules, WinDivert, REPL               |
| Protocol         | Message types, encryption scheme, framing                      |
| REST API         | All endpoints, token scopes, examples                          |
| Web Dashboard    | Graph view, real-time updates, features                        |
| Chrome Extension | Setup and features                                             |
| Configuration    | All config fields and defaults                                 |
| Security         | Encryption, auth, sessions, rate limiting                      |
| Building         | Cross-compilation, build.sh usage                              |
| Dependencies     | Server and agent dependency list                               |

***

## Quick Start

**1. Start the server (requires root/admin):**

```bash
sudo rosemary
```

or specify a key

```bash
sudo rosemary -key <base64-key>
```

**2. Run an agent on the remote host:**

```bash
./agent-linux-amd64 -s <server-ip>:2048 -k <base64-key>
```

**3. PowerShell Agent:**

```powershell
Invoke-Rosemary -Mode agent -Server <server-ip>:2048 -Key <base64-key>
```

PowerShell outbound mode requires PowerShell 7 with .NET QUIC support. On legacy Windows PowerShell hosts, use `agent-bind` mode or the Go Windows agent.

**4. Open the dashboard:**

```
http://<server-ip>:1024
```

All traffic to the agent subnets is now transparently routed through it.

***

## Platform Support

| Platform                        | Server | Agent |
| ------------------------------- | ------ | ----- |
| Linux amd64 / arm64 / arm / 386 | yes    | yes   |
| Windows amd64 / 386             | yes    | yes   |
| macOS amd64 / arm64             | yes    | yes   |
| FreeBSD amd64 / arm64           | yes    | yes   |
| OpenBSD amd64 / arm64           | yes    | yes   |