Home

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)   |  WebSocket  | HTTP + REST API  :1024     |
|                   +<----------->+ WS endpoint      /ws       |
| - subnet discovery| AES-256-GCM | TCP proxy        :1080     |
| - TCP forwarding  | yamux mux   | 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

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

Or download pre-built binaries from the Releases page.

---

Pages

Page	Description
Getting Started	Installation, first agent, config examples
Architecture	Transport layer, yamux stack, 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):

sudo rosemary -k <base64-key>

2. Run an agent on the remote host:

./agent-linux-amd64 -s <server-ip>:1024 -k <base64-key>

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