> 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   |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://rosemary-2.gitbook.io/rosemary-docs/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.