Getting Started

This guide takes you from zero to a live agent that you can send messages to and stream responses from.

Prerequisites

• A dashboard account with whitelisted_user or admin access (W3 ID sign-in).
• A place to run the runtime binary — your laptop, a server, or a container.

1. Create a project

A project is the unit of organization: it owns a workspace, members, agents, and a usage quota. Create one from Projects → New Project in the dashboard.

Each project gets a workspace folder (for files and an optional AGENTS.md) and a skills/ folder automatically.

2. Create an agent

Open your project and use Create agent. The agent is a project-scoped record that can be issued tokens. On creation you receive a bootstrap token.

3. Download the runtime

From the agent page, download the binary for your platform:

Unzip it. The bundle contains the binary and a lib/ folder (required only if you use browser automation):

agent22-{platform}/
├── agent22          # the runtime binary
└── lib/
    └── rebrowser-playwright/
        └── node_modules/playwright-core/

4. Run the agent

Pick a home directory where the agent will store all of its state (SQLite DB, config, logs, browser profiles), then start it:

# TCP port (default 4484)
./agent22 --home /data/my-agent --port 4484 --api-key "$BOT_AGENT_API_KEY"

Poll GET /health until it returns 200 { "status": "ok" } before continuing.

5. Authenticate (once)

The runtime never holds LLM keys. Instead, it exchanges the bootstrap token from step 2 for a JWT session against the control plane:

curl -X POST http://localhost:4484/auth/session \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BOT_AGENT_API_KEY" \
  -d '{"cloudBaseUrl":"https://169.63.180.31.sslip.io","bootstrapToken":"<token>"}'
# → { "signedIn": true, "productId": "...", "deviceId": "...", "entitlements": {...} }

The dashboard's agent page shows a ready-to-copy version of this command with your cloudBaseUrl pre-filled. The runtime caches the session and refreshes tokens automatically.

6. Send a message and stream the response

Messaging is asynchronous — POST /messages returns 202 immediately, and you receive the assistant reply over WebSocket.

// 1. Create a conversation
const conv = await fetch("http://localhost:4484/conversations", {
  method: "POST",
  headers: authHeaders(),
  body: JSON.stringify({
    title: "My Assistant",
    workspacePath: "/home/me/project",
  }),
}).then((r) => r.json());

// 2. Send a message (returns 202 right away)
await fetch(`http://localhost:4484/conversations/${conv.id}/messages`, {
  method: "POST",
  headers: authHeaders(),
  body: JSON.stringify({ content: "Hello, what can you do?" }),
});

// 3. Stream the response
const ws = new WebSocket(
  `ws://localhost:4484/conversations/${conv.id}/ws?api_key=${KEY}`,
);
ws.onmessage = (e) => {
  const evt = JSON.parse(e.data);
  if (evt.type === "message.delta") appendToUi(evt.data.delta); // stream tokens
  if (evt.type === "run.completed") markDone();
};

That's a working agent. The full HTTP/WebSocket reference, plus features like cancellation, crons, forking, compaction, and subagents, is in Agent API: Getting started.

Next steps

• Learn how the runtime loop and tools work.
• Run it reliably: Deployment.
• Read the full HTTP/WebSocket reference.