Configuration

Configuration

Both the server and agent can be configured via CLI flags or a JSON config file. The config file takes the same values as the flags.

---

Server Configuration

Pass a config file with -config:

sudo rosemary -config server.json

Fields

Field	Type	Default	Description
key	string	auto-generated	Base64url-encoded 32-byte AES-256 key
http_port	int	1024	Web dashboard and REST API port
tcp_port	int	1080	TCP transparent proxy port
udp_port	int	1081	UDP TPROXY port
dns_port	int	5300	DNS intercept proxy port
session_idle_minutes	int	30	Dashboard session idle timeout in minutes

Example

{
  "key": "your-base64url-32-byte-key-here",
  "http_port": 1024,
  "tcp_port": 1080,
  "udp_port": 1081,
  "dns_port": 5300,
  "session_idle_minutes": 30
}

The QUIC agent transport port defaults to 2048/udp and is configured with the server -agent-port flag.

---

Agent Configuration

Pass a config file with -c:

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

Fields

Field	Type	Default	Description
key	string	required	Base64url-encoded 32-byte AES-256 key
server_addr	string	required	Server agent transport address, e.g. <ip>:2048
mode	string	agent	agent for outbound connect, agent-bind for listen mode

Example (standard mode)

{
  "key": "your-base64url-32-byte-key-here",
  "server_addr": "<server-ip>:2048",
  "mode": "agent"
}

Example (bind mode)

{
  "key": "your-base64url-32-byte-key-here",
  "mode": "agent-bind"
}

Bind-mode listen address is set with the -l flag. The default is 0.0.0.0:9001.

---

Generating a Key

Both server and agent must share the same key. Generate a valid key with:

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

The key must be exactly 32 bytes decoded, encoded as base64url without padding.

---

Saving and Loading Config from the REPL

Export the current server config:

save-config /path/to/server.json

Import a config file at runtime:

load-config /path/to/server.json

---

Live Configuration Changes

The following can be changed at runtime from the REPL without restarting the server:

• port <n> — HTTP port
• tcp-port <n> — TCP proxy port
• udp-port <n> — UDP proxy port
• dns-port <n> — DNS proxy port
• rotate-key — Generate and apply a new random key
• verbose — Toggle debug logging

Settings can also be changed via PATCH /api/v1/settings with an admin token.