@boxgo/agent

The Boxgo server agent — the single root process that runs on your own server (bring-your-own-server). It keeps a persistent, token-authenticated WebSocket to the Boxgo control plane.

Install

Add a server in the Boxgo panel, then run the one-liner it gives you on the server (as root):

curl -fsSL https://boxgo.dev/install.sh | bash -s -- <token>

install.sh installs the base packages, Node, msb and caddy, hardens the host, and finishes with the manual steps below. If the prerequisites are already in place:

npm install -g @boxgo/agent
boxgo-agent install --token <token>

MicroSandbox SDK compatibility

Boxgo speaks the MicroSandbox cloud REST API for sandbox and volume lifecycle, so the MSB SDKs and CLI can target your own servers:

export MSB_BACKEND=cloud
export MSB_API_KEY="boxgo_..."          # an API key from the Boxgo panel
export MSB_API_URL="https://boxgo.dev/api"

Create, start, stop, list, remove and named volumes work as on cloud. exec, file transfer, SSH and log following are not relayed yet (the API answers 501). The relay endpoint is a WebSocket one, so an SDK exec() surfaces as a WebSocket handshake failure rather than that message.

Commands

| Command | What it does | | --------------------------------------------------------- | --------------------------------------------------------------- | | boxgo-agent run | Starts the agent (what the systemd unit executes) | | boxgo-agent install --token <t> [--control-plane <url>] | Writes .env + unit, enables and (re)starts the service (root) | | boxgo-agent status | systemctl is-active + the last logs | | boxgo-agent logs [-f] | Last logs (-f to follow) | | boxgo-agent update | npm install -g @boxgo/agent@latest + systemctl restart |

Paths

• /etc/boxgo-agent/.env — identity (CONTROL_PLANE_URL, AGENT_TOKEN), mode 0600
• /etc/systemd/system/boxgo-agent.service — unit (StateDirectory=boxgo-agent)
• /var/lib/boxgo-agent/boxes — port claims (<id>_<port>.caddy; env PORTS_DIR)
• /etc/caddy/boxes — box vhosts (<id>.caddy; env CADDY_BOXES_DIR)

Development

AGENT_TOKEN=<token> npm run dev   # build + agent against CONTROL_PLANE_URL=http://localhost:8000 + tsc --watch
npm test                          # prettier + xo + node --test

Without AGENT_TOKEN the channel stays off (channel disabled: AGENT_TOKEN unset). On macOS the vhost and claim directories default to /tmp/caddy/boxes and /tmp/agent/boxes.

Publishing: npm publish (prepack runs the build; only dist/ is shipped).

License

Apache-2.0 — see LICENSE.