revka gateway, daemon & service

These commands run the Revka HTTP runtime: revka gateway for the dashboard and API alone, revka daemon for the full autonomous runtime, and revka service to keep either alive as an OS-managed background service. This page is the reference for all three, plus the pairing-code workflow and the bind-host restrictions that gate network exposure.

Reach for revka gateway for local dashboard work, revka daemon for production (channels, heartbeat, and cron together), and revka service once you want Revka to start on login or boot and survive crashes. For a first-time, click-through walkthrough see Run the dashboard; for OS-by-OS service detail see Run as a background service.

revka gateway

revka gateway starts just the HTTP/WebSocket gateway: the embedded React dashboard at /, the REST API under /api/*, the Server-Sent Events stream at /api/events, and the WebSocket endpoints (/ws/chat, /ws/canvas/{id}, /ws/nodes). It does not start channels, the heartbeat, or the cron scheduler — use revka daemon for those.

revka gateway                        # start on config defaults
revka gateway start                  # explicit start
revka gateway start -p 8080          # custom port
revka gateway start --host 0.0.0.0   # bind all interfaces (see bind restrictions)
revka gateway start -p 0             # bind a random available port
revka gateway restart                # graceful restart
revka gateway restart -p 9090
revka gateway get-paircode           # show the current pairing code
revka gateway get-paircode --new     # rotate to a fresh pairing code

Subcommands and flags

Subcommand	Flags	Purpose
start	-p / --port <u16> (0 = random), --host <STRING>	Start the gateway. Bare revka gateway is equivalent to revka gateway start.
restart	-p / --port <u16>, --host <STRING>	Graceful restart with the same flags as start.
get-paircode	--new	Print the current pairing code, or rotate to a fresh one with --new.

The default bind is 127.0.0.1:42617. The listen port is read from [gateway].port in your config (schema default 42617), and --port/--host override the config per invocation. The process prints its URL on startup.

Note

When [gateway].require_pairing is true (the default), the gateway prints a one-time pairing code on first start. Exchange it for a bearer token using pairing codes below.

revka daemon

revka daemon launches the complete Revka runtime as a single foreground process: the gateway server, every configured channel supervisor (Telegram, Discord, Slack, and so on), the heartbeat monitor, and the cron scheduler. This is the recommended production entrypoint — register it with revka service so the OS keeps it alive.

revka daemon                    # use config defaults
revka daemon -p 9090            # gateway on port 9090
revka daemon --host 127.0.0.1   # localhost only
revka daemon --host 0.0.0.0     # all interfaces (requires allow_public_bind)

Flag	Default	Meaning
-p / --port <u16>	[gateway].port	Gateway listen port. 0 binds a random available port.
--host <STRING>	[gateway].host	Bind address. Non-loopback addresses are gated — see bind restrictions.
--config-dir <PATH>	~/.revka	Global flag; must precede the subcommand. Also sets REVKA_CONFIG_DIR for the process.

The daemon terminates cleanly on SIGINT or SIGTERM. SIGHUP is explicitly ignored, so the process survives an SSH or terminal disconnect. A warning is logged if the binary is running from a user home directory instead of a system install location such as /usr/local/bin.

Component supervisor

Each of the four daemon components — gateway, channels, heartbeat, scheduler — runs in its own task wrapped by a supervisor. On crash or exit, the supervisor waits channel_initial_backoff_secs (default 2), then doubles the delay on each subsequent failure up to channel_max_backoff_secs (default 60) before restarting. The restart count and last error are recorded in the health snapshot.

[reliability]
channel_initial_backoff_secs = 2   # initial retry delay (minimum 1)
channel_max_backoff_secs     = 60  # exponential cap; must be >= initial

Key	Type	Default	Meaning
reliability.channel_initial_backoff_secs	integer	2	Initial retry delay in seconds. Minimum 1.
reliability.channel_max_backoff_secs	integer	60	Exponential backoff cap. Must be greater than or equal to the initial value.

Note

A clean exit still triggers the restart cycle (with reset backoff). No component is expected to exit unless the daemon itself is shutting down, so repeated restarts in the logs point at a component that keeps failing — check the recorded last error.

Daemon state file

While running, the daemon writes daemon_state.json alongside config.toml (<config_dir>/daemon_state.json) every 5 seconds. The file contains a health snapshot of every component and a written_at timestamp.

• Liveness monitoring — a state file older than 45 seconds means the daemon has died. External monitors can poll this file directly.
• Windows — revka service start reads this file to detect whether a direct-daemon fallback is already running, because the Windows Task Scheduler cannot be queried reliably.

Pairing codes and tokens

Every /api/* request carries Authorization: Bearer <token>, and that token is minted by exchanging a one-time pairing code. Pairing is what stops an unknown client on your network from driving your agent.

Show or rotate the code from the CLI

revka gateway get-paircode          # show the current code
revka gateway get-paircode --new    # rotate to a fresh code

These call the localhost-only admin endpoints GET /admin/paircode and POST /admin/paircode/new. Codes are single-use: once a client pairs with a code it is consumed, and you must rotate to issue another.

Exchange a code for a token (revka pair token)

revka pair token exchanges a pairing code for a bearer token from the command line — useful for pairing a headless device or a script.

revka pair token --code 123456
revka pair token --code 123456 --name "Field phone" --device-type mobile --hardware "Pixel 8 / Android"
revka pair token --url http://revka.local:8080 --code 123456 --json
revka pair token --code 123456 --host 192.168.1.10 --port 8080

Flag	Required	Meaning
--code <STRING>	yes	The one-time pairing code.
--url <URL>	no	Full gateway base URL, e.g. http://127.0.0.1:8080.
--host <STRING>	no	Gateway host, used when --url is omitted.
-p / --port <u16>	no	Gateway port, used when --url is omitted.
--name <STRING>	no	Device name shown on the dashboard Pairing page.
--device-type <STRING>	no	Device type label. Default: cli.
--hardware <STRING>	no	Hardware / platform label, e.g. Pixel 8 / Android.
--json	no	Print machine-readable JSON instead of human text.

Under the hood this posts the code to the gateway and returns the bearer token:

POST /api/pair
Content-Type: application/json

{
  "code": "123456",
  "device_name": "Field phone",
  "device_type": "mobile",
  "hardware": "Pixel 8 / Android"
}

{
  "token": "<bearer-token>",
  "persisted": true,
  "message": "Pairing successful"
}

Caution

The plaintext token is printed exactly once and the gateway stores only a hash. Save it immediately. --device-type and --hardware are informational labels only, visible on the dashboard Pairing page.

For the dashboard-side flow, QR-based device pairing, and device revocation, see Pairing & authentication and Secrets, pairing & device auth.

Bind restrictions

The gateway can bind to 127.0.0.1 (localhost only — the default), 0.0.0.0 (all IPv4 interfaces), or [::] (all IPv6 interfaces). Binding to any non-loopback address without allow_public_bind = true (and no active tunnel) logs a warning but still binds. This is a deliberate safety default — 0.0.0.0 exposes the gateway to every connected network.

[gateway]
host = "0.0.0.0"
port = 42617
allow_public_bind = true

revka daemon --host 127.0.0.1    # localhost only (default)
revka daemon --host 0.0.0.0      # LAN access — needs allow_public_bind = true

Key	Type	Default	Meaning
gateway.host	string	127.0.0.1	Bind address. Inside Docker containers the default is [::].
gateway.port	integer	42617	Listen port. 0 binds a random available port.
gateway.allow_public_bind	boolean	false	Must be true to bind any non-loopback address.

Both keys have environment overrides for containers and CI: REVKA_GATEWAY_HOST / HOST, REVKA_GATEWAY_PORT / PORT, and REVKA_ALLOW_PUBLIC_BIND.

REVKA_ALLOW_PUBLIC_BIND=true revka gateway start --host 0.0.0.0

Caution

For public internet exposure, prefer keeping the gateway on 127.0.0.1 and fronting it with a tunnel rather than binding 0.0.0.0 directly. See Expose your gateway with a tunnel and Network deployment, Raspberry Pi & proxy.

OS Service Management

revka service runs revka daemon as a persistent, OS-managed background service so it starts automatically and is restarted on failure. The init system is auto-detected per platform:

• macOS — a launchd agent at ~/Library/LaunchAgents/com.revka.daemon.plist (RunAtLoad and KeepAlive enabled).
• Linux — a systemd user unit at ~/.config/systemd/user/revka.service (no root required), or an OpenRC init script at /etc/init.d/revka.
• Windows — a Scheduled Task named Revka Daemon that runs at logon, with a direct background-spawn fallback if the scheduler is unavailable.

Commands

revka service install
revka service start
revka service stop
revka service restart
revka service status
revka service logs -n 100 --follow
revka service logs
revka service uninstall

# Override the init system (Linux only)
revka service --service-init systemd install
revka service --service-init openrc install

Subcommand	Purpose
install	Generate and register the service unit / plist / scheduled task.
start	Start the service. Rotates daemon logs first if they exceed 20 MB.
stop	Stop the running service.
restart	Stop then start.
status	Report whether the daemon is running. Also checks the 45-second-fresh daemon state file as a fallback.
logs	Tail the daemon logs. -n / --lines <N> sets the line count (default 50); -f / --follow streams new output like tail -f.
uninstall	Remove the service unit / plist / scheduled task.

Flag	Values	Default	Meaning
--service-init	auto, systemd, openrc	auto	Force a specific init system on Linux. Applies to all subcommands.

--service-init

revka service auto-detects the right init system, but on Linux you can force one with --service-init. Pass it before the subcommand:

• auto (default) — detect systemd, OpenRC, launchd, or Windows Task Scheduler automatically.
• systemd — install a systemd user unit. Runs systemctl --user enable revka.service so it starts on login. For start-on-boot without an active session, enable lingering with loginctl enable-linger $USER.
• openrc — install an OpenRC init script. System-wide and root-only; see the Linux tab below.

Per-platform notes

macOS (launchd)

The launchd agent runs revka daemon with RunAtLoad and KeepAlive. Homebrew installs are detected automatically: the service then uses <brew_prefix>/var/revka/logs/ for logs and carries REVKA_CONFIG_DIR as an environment key in the plist, so config and workspace data survive brew upgrade. The plist raises the file-descriptor limit (SoftResourceLimits/HardResourceLimits for NumberOfFiles, 4096 soft / 8192 hard) to avoid “Too many open files” when many MCP servers run at once.

brew services start revka uses the same plist.

revka service install
revka service start

Linux (systemd)

The systemd user unit runs revka daemon with Restart=always and RestartSec=3, sets LimitNOFILE=4096:8192, injects a curated PATH (covering ~/.cargo/bin, ~/.local/bin, /opt/homebrew/bin, plus the install-time PATH), passes DISPLAY and XDG_RUNTIME_DIR for headless browser support, and orders after network.target. No root is required.

revka service install
revka service start
loginctl enable-linger $USER     # optional: start on boot without an active login

Alpine / OpenRC

OpenRC is system-wide and requires root. Installation creates /etc/init.d/revka, creates a revka:revka system user (UID < 1000, shell /sbin/nologin), sets ownership on /etc/revka/, /var/lib/revka/, and /var/log/revka/, and migrates an existing ~/.revka config into /etc/revka on first install.

sudo revka service install        # auto-detects OpenRC on Alpine
sudo rc-update add revka default
sudo rc-service revka start

A pre-existing revka user with UID ≥ 1000 or a non-nologin shell causes a clear error with remediation steps.

Windows

revka service install registers a Scheduled Task named Revka Daemon via schtasks /SC ONLOGON that launches the daemon at user logon — no elevation required. A .cmd wrapper with a snapshotted PATH is placed in the config logs directory. If the Task Scheduler is unavailable, Revka falls back to a direct background spawn and prints instructions to run revka service install later.

revka service install
revka service start
revka service status
revka service logs --follow
revka service uninstall

Logs are written to <config_dir>/logs/daemon.stdout.log and daemon.stderr.log; revka service logs --follow uses PowerShell Get-Content -Wait.

Log rotation

Before revka service start, daemon logs are rotated if they exceed 20 MB. Up to 5 rotated copies are kept (daemon.stdout.log.1 through .5); the oldest is deleted before renaming. Logs live in the Homebrew var/revka/logs/ directory or <config_dir>/logs/.

Note

Rotation only triggers on service start, not while the daemon runs continuously. Long-lived services rotate at the next restart.

Quick start: install and run as a service

1. Install the service. The init system is auto-detected.

   revka service install

2. Start it.

   revka service start

3. Confirm it is healthy. Check the service state and the public health endpoint.

   revka service status
   curl http://127.0.0.1:42617/health

4. Pair a client. Read the pairing code and exchange it for a token.

   revka gateway get-paircode
   revka pair token --code 123456

Verifying and troubleshooting

• Liveness. GET /health returns 200 with pairing status and a component snapshot and needs no auth — ideal for load balancers. revka status --format exit-code exits 0 when healthy and 1 otherwise (the canonical Docker HEALTHCHECK). Run revka doctor for structured diagnostics.
• Service won’t start (Windows). revka service status also consults the daemon state file; a state file fresher than 45 seconds means a daemon is already running.
• Restart loops in the logs. A component keeps failing and the supervisor keeps restarting it with growing backoff. Check the recorded last error and tune reliability.channel_max_backoff_secs.
• Can’t reach the gateway from another machine. The default bind is loopback-only. Set allow_public_bind = true or front it with a tunnel.
• Pairing input rejects your code. Codes are single-use. Rotate with revka gateway get-paircode --new and try again.

Next steps

Run as a background service OS-by-OS service setup for launchd, systemd, OpenRC, and Windows Task Scheduler.

Run the dashboard Start the gateway, pair your browser, and tour the web UI.

Pairing & authentication The full gateway pairing flow, device registry, and bearer tokens.

Expose your gateway with a tunnel Reach a localhost gateway from the public internet safely.