Deployment

You download the runtime binary from the dashboard and run it yourself — on a laptop, a server, or in a container. Your application spawns it as a child process and communicates with it exclusively over HTTP and WebSocket.

Get the binary

Download from the agent page in the dashboard:

The bundle must include both the binary and the lib/ folder. The runtime works fine without lib/ if you don't use browser automation.

agent22-{platform}/
├── agent22
└── lib/
    └── rebrowser-playwright/node_modules/playwright-core/

Spawn the runtime

Desktop app (Node / Electron)

import { spawn } from "node:child_process";
import path from "node:path";

const homeDir = path.join(app.getPath("userData"), "agent22");

const proc = spawn(
  "./agent22",
  [
    "--home",
    homeDir,
    "--port",
    "4484",
    "--api-key",
    process.env.BOT_AGENT_API_KEY,
    "--cloud-url",
    "https://169.63.180.31.sslip.io",
  ],
  { stdio: ["ignore", "pipe", "pipe"] },
);

proc.stdout.on("data", (d) => console.log("[agent]", d.toString()));
proc.on("exit", (code) => console.log(`agent exited with code ${code}`));

Web / server backend

spawn("./agent22", [
  "--home",
  "/data/my-agent",
  "--port",
  "4484",
  "--api-key",
  process.env.BOT_AGENT_API_KEY,
  "--cloud-url",
  "https://169.63.180.31.sslip.io",
  "--chrome-url",
  "ws://chrome:9222", // remote Chrome for server environments
]);

Don't pipe user-facing strings to the process stdin — stdin is ignored. Use stdio: ["ignore", ...].

Port vs. unix socket

Use --port when the UI connects directly from a browser; browsers can't open WebSocket over a unix socket.

CLI parameters

CLI args take precedence over env vars. .env and .env.local in the working directory are auto-loaded on startup.

Browser setup (optional)

Two modes:

Local Chrome (desktop) — default. The runtime launches a persistent Chrome instance on the user's machine (point to a binary with CHROME_EXECUTABLE_PATH). Each conversation gets an isolated browser profile, so cookies/localStorage persist per conversation but don't bleed across them.

Remote Chrome via CDP (server) — connect to an external Chrome instance. Set --chrome-url / CHROME_CDP_URL:

./agent22 --chrome-url ws://localhost:9222

Works with Docker Chrome containers (selenium/standalone-chrome, browserless/chrome), managed browser services, or a Chrome fleet behind a load balancer.

Lifecycle

Startup: poll GET /health until 200 { "status": "ok" } before sending other requests. The runtime boots its SQLite DB, cron scheduler, and HTTP listener during startup.

Graceful shutdown: send SIGTERM (or SIGINT). The runtime stops accepting new connections, then waits up to 5 minutes for active conversations to drain so in-flight runs complete cleanly, then exits.

proc.kill("SIGTERM");

Security considerations

• Always set --api-key in production to prevent unauthorized access to the local HTTP API. The key is only for the local server — it's never sent to the control plane.
• Cloud auth uses JWT tokens with refresh rotation; tokens live in cloud.json (treat as a credential — don't commit it).
• The runtime has full shell access via the bash tool — only run it in trusted environments.
• Browser sessions are isolated per conversation.

See Security for the full model.