Getting Started

Getting Started

This page covers how to install and run Rosemary for the first time, from downloading the binaries to connecting your first agent.

---

Requirements

Server:

• Linux, Windows, or macOS
• Root or Administrator privileges (required for kernel-level interception)
• Ports 1024, 1080, 1081, 5300 available (all configurable)

Agent:

• Linux, Windows, macOS, FreeBSD, or OpenBSD
• No root required
• Outbound access to the server on port 1024

---

Installation

Option 1: go install

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

Binaries will be placed in ~/go/bin/. To use with sudo, copy to system path:

sudo cp ~/go/bin/rosemary /usr/local/bin/

Option 2: Pre-built Binaries

Pre-built binaries are available in the dist/ directory of the repository for all supported platforms.

Naming format:

rosemary-<os>-<arch>
agent-<os>-<arch>

Examples:

rosemary-linux-amd64
rosemary-windows-amd64.exe
agent-linux-amd64
agent-windows-amd64.exe
agent-darwin-arm64

---

Generating a Key

Both the server and agent share a 32-byte AES-256 key encoded as base64url. Generate one with:

openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

Keep this key secret. Any agent that knows the key can connect to your server.

---

Starting the Server

Linux / macOS (requires root):

sudo rosemary

OR with specified key

sudo rosemary -k <your-base64-key>

Windows (requires Administrator):

rosemary-windows-amd64.exe -k <your-base64-key>

OR with specified key

rosemary-windows-amd64.exe -k <your-base64-key>

The server starts on the following default ports:

Service	Port
Web dashboard and REST API	1024
TCP transparent proxy	1080
UDP transparent proxy	1081
DNS proxy	5300

Open the dashboard at:

http://<server-ip>:1024

The default login uses the AES key as the password.

---

Running an Agent

Copy the agent binary to the remote host and run:

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

The agent will:

1. Connect to the server over WebSocket
2. Authenticate using the shared key
3. Discover its local subnets and internet status
4. Register with the server
5. Begin forwarding traffic

Once registered, the server installs interception rules for the agent subnets and all matching traffic is transparently tunneled.

---

Running the Agent in the Background

Add the -b flag to daemonize the agent:

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

On Unix this uses setsid to detach from the terminal. On Windows it uses a detached process.

---

Using a Config File

Instead of passing flags each time, create a JSON config file.

Server config (server.json):

{
  "http_port": 1024,
  "tcp_port": 1080,
  "udp_port": 1081,
  "dns_port": 5300,
  "key": "<your-base64-key>",
  "session_idle_minutes": 30,
  "ws_path": "/ws"
}

sudo rosemary -c server.json

Agent config (agent.json):

{
  "key": "<your-base64-key>",
  "server_addr": "<server-ip>:1024",
  "mode": "agent"
}

./agent-linux-amd64 -c agent.json

---

Verifying the Connection

Once the agent connects, open the dashboard at http://<server-ip>:1024. You should see the agent appear in the graph or table view with its hostname, OS, username, and discovered subnets.

From the server REPL you can also run:

agents

This lists all connected agents with their IDs, hostnames, and subnets.

---

Agent Bind Mode

If the agent cannot reach the server (e.g. behind a strict firewall), use bind mode. The agent listens on a local port and the server connects to it.

On the remote host:

./agent-linux-amd64 -m agent-bind -p 4444 -k <your-base64-key>

From the server REPL:

connect <remote-ip>:4444

---

Next Steps

Page	Description
Architecture	How the tunneling and interception works in depth
Agent	All agent modes and CLI flags
Server	Proxy listeners, REPL commands, iptables rules
Configuration	Full reference for all config fields
Security	Key management, auth, and hardening