Remote Access — Deploy VulpineOS on a VPS

VulpineOS supports running the browser kernel on one machine and controlling it from another. The remote control plane has two operator modes:

Remote panel — open the embedded browser dashboard in your local browser
Remote TUI — run the terminal workbench against the remote runtime

Three Modes

1. Local (Default)

TUI and kernel on the same machine. No network involved.


./vulpineos

2. Serve Mode

Expose the runtime, web panel, and control API over the network:


./vulpineos serve --host 0.0.0.0 --port 8443 --no-tls --api-key YOUR_SECRET_KEY

This starts:

The Firefox kernel
An HTTP/WebSocket server on the specified port
The embedded web panel at /
A /health endpoint for monitoring
A /ws endpoint for panel and TUI connections

If --api-key is omitted, VulpineOS generates one at startup and prints both the access key and a direct panel URL containing the token.

3. Remote Panel

Open the remote panel in your local browser:


./vulpineos remote --url http://your-vps:8443 --api-key YOUR_SECRET_KEY
# or explicitly:
./vulpineos remote panel --url http://your-vps:8443 --api-key YOUR_SECRET_KEY

If you omit the explicit remote mode, panel is the default.

4. Remote TUI

Connect the terminal workbench to a remote runtime:


./vulpineos remote tui --url http://your-vps:8443 --api-key YOUR_SECRET_KEY

The TUI behaves identically to local mode — all panels, keybinds, and agent management work the same way. The WebSocket transport replaces the local pipe transport.

Authentication

Access-key authentication supports two methods:

Header: Authorization: Bearer YOUR_KEY
Query parameter: ?token=YOUR_KEY

Keys are compared using constant-time comparison to prevent timing attacks. The browser login form validates explicit keys through /auth/check, while the panel websocket continues to use the tokenized URL path required by browser WebSocket clients.

Relay Protocol

The WebSocket connection multiplexes three message types:

Type	Direction	Purpose
`juggler`	Bidirectional	Juggler protocol messages (commands + responses)
`control`	Client → Server	Administrative commands
`tui_state`	Server → Client	State updates for TUI rendering

All browser events (telemetry updates, injection alerts, trust-warming state changes) are automatically broadcast to all connected clients.

Health Check


curl http://your-vps:8443/health
# → {"status": "ok", "uptime": 3600, "contexts": 5}

Network Requirements

Port: configurable (default 8443)
Protocol: WebSocket (ws:// or wss://)
Bandwidth: minimal — only JSON messages, not video/screenshots unless requested
Latency: TUI remains responsive up to ~200ms RTT

Security Considerations

Use --no-tls only behind a trusted network or reverse proxy; use wss:// / https:// (TLS) in production
Provide a strong explicit access key when you need a stable credential
Panel access keys are stored only for the current browser session
The server does not expose the kernel binary or filesystem — only Juggler protocol access
Each connected client gets its own message queue; one slow client cannot block others

Files

internal/remote/server.go — HTTP/WS server with /ws and /health
internal/remote/client.go — WS client implementing juggler.Transport
internal/remote/auth.go — API key authenticator
internal/remote/relay.go — Envelope types for multiplexing