# sandbox-platform — agent bootstrap (llms.txt)

> Cloud sandboxes, browsers and desktops for AI agents — plus the CLIs to drive them.
> This file is the bootstrap entrypoint for an AI agent: follow it top to bottom to get
> a key, learn the typed API, pick a CLI, and make your first call. Base URL:
> https://sandbox.service.ab0t.com . Everything linked below is served by this service.

## What this is
A control plane that gives an agent its own cloud compute: ephemeral **sandboxes** (Linux
shells you exec into), headless **browsers** (drive Chrome/Firefox), and full **desktops**
(XFCE GUI/RPA). You drive it two ways — the **typed REST API** directly, or one of the two
**CLIs** that wrap it. The one thing you need first is an **API key**.

## Get access (no browser needed)
Self-onboarding is REST-only against the auth service (https://auth.service.ab0t.com). Use the
**org-scoped** register endpoint — it enrols you with the sandbox permissions you need:

1. Register into the sandbox users org (no auth, no invite) -> returns a JWT:
   curl -X POST https://auth.service.ab0t.com/organizations/sandbox-platform-users/auth/register \
     -H 'Content-Type: application/json' \
     -d '{"email":"you@example.com","password":"<8+ chars upper/lower/digit/special>","name":"My Agent"}'
   # -> { "access_token": "<JWT>", ... }
   WARNING: use this org-scoped URL, NOT the bare /auth/register — the bare one puts you in an
   empty personal org with no sandbox permissions and step 3 will fail.

2. Try step 3 immediately — a key is often mintable right away. If step 3 instead returns
   403 "Cannot create API key with permissions you don't hold", that means "not ready yet"
   (your sandbox.* permissions provision asynchronously, sometimes a few minutes), NOT "wrong".
   Only then poll step 3 with backoff (re-login first to refresh your JWT) until it returns 200.

3. Mint a long-lived API key with your JWT (scope it to what you need):
   curl -X POST https://auth.service.ab0t.com/api-keys/ \
     -H "Authorization: Bearer <JWT>" -H 'Content-Type: application/json' \
     -d '{"name":"my-agent","permissions":["sandbox.read.sandboxes","sandbox.create.sandboxes","sandbox.execute.commands"]}'
   # 403 -> perms not provisioned yet, wait + retry;  200 -> { "key_id": "...", "key": "ab0t_sk_..." } (save it, shown once)

4. Call this service with the key:
   curl https://sandbox.service.ab0t.com/api/sandboxes -H "X-API-Key: ab0t_sk_..."

Notes that bite agents:
- JWT vs key: the JWT is short-lived (~15 min) and only used to MINT keys; the ab0t_sk_ key is
  long-lived and what you send on every API call. A key cannot mint another key.
- No machine grant (client_credentials / device-code) exists yet — password self-register is the
  only headless path today.
- register is rate-limited ~5/min/IP — space out bulk onboarding.

## The typed API
Full typed contract: https://sandbox.service.ab0t.com/openapi.json (FastAPI; every route has a
typed response model). Deeper guide: the sandbox-platform-api skill.
Auth: send EITHER `Authorization: Bearer <JWT>` OR `X-API-Key: ab0t_sk_...` — both work; agents
should use X-API-Key. (The WebSocket terminal takes ?token=; auth-fail closes with code 4001.)

First-call endpoints (method · path · permission):
- POST /api/sandboxes        · sandbox.create.sandboxes  — create a Linux sandbox
- POST /api/browsers         · sandbox.create.sandboxes  — create a cloud browser
- POST /api/desktops         · sandbox.create.sandboxes  — create a cloud desktop
- GET  /api/sandboxes        · sandbox.read.sandboxes    — list yours
- POST /api/sandboxes/{id}/execute · sandbox.execute.commands — run a command
- DELETE /api/sandboxes/{id} · sandbox.delete.sandboxes  — terminate
Other tag groups in the spec: My Computers, Containers, Costs, Quotas, SSH Keys/Certificates, Support, Pricing, Health.

## My Computers — a PERSISTENT machine, not a throwaway (OpenAPI tag: "My Computers")
A Computer is a named, owned desktop with an off/on lifecycle: it keeps its identity (and,
where persistence is enabled, its files at /config) across stop/resume. Create one by adding
`computer_name` (and optionally `blueprint_id`) to POST /api/desktops with
`desktop_type:"ubuntu-xfce-agent"` (the agent-ready image).

The journey (each step is a typed route in /openapi.json):
1. GET  /api/capabilities                    — {persistence_enabled, export_available}: the LIVE
   truth for THIS environment. Never promise file survival without checking it.
2. GET  /api/blueprints                      — curated configs you may use (platform ∪ org ∪ own);
   POST /api/blueprints authors one (org/platform scopes are permission-gated).
3. POST /api/desktops {computer_name, blueprint_id?, desktop_type:"ubuntu-xfce-agent"}
   — resources are REQUESTS, tier-clamped (`resource_clamped` in the response is the honest flag).
4. GET  /api/containers/{id}/status          — until state=assigned; then
   GET  /api/containers/{id}/manager-status  — until healthy=true (the REAL readiness probe); then
   GET  /api/containers/{id}/agent-bootstrap — {manager_url, manager_token, install_cmd, connect_cmd}.
5. DRIVE the machine via its manager (:1337, Bearer manager_token): POST {manager_url}/execute ·
   /files/upload|download|list · /rpa/* (screenshot/click/type/ocr/computer-use) ·
   /workflow/execute (multi-step) · WS /ws/terminal. The manager self-documents:
   GET {manager_url}/llm.txt and {manager_url}/skills — read those once connected.
   Keep anything that must survive under /config.
6. POST /api/containers/{id}/stop | /resume  — Turn off / Turn on. Off computers stay listed in
   GET /api/computers. With persistence lit, stop snapshots /config first (a failed snapshot
   ABORTS the stop) and resume restores it — files intact.
7. POST /api/computers/{id}/export           — presigned tar.zst of /config ("take your home");
   PATCH /api/computers/{id} {computer_name} — rename;
   GET  /api/computers/{id}/storage · GET /api/storage/usage — size/quota gauges;
   POST /api/computers/{id}/recreate         — bring a deleted computer back onto its surviving home;
   DELETE /api/computers/{id}/home           — right-to-delete: purge the files for good.
Error grammar: 404 on /api/computers/* = "not yours or doesn't exist" (indistinguishable by
design); 409 = lifecycle conflict (read the static detail); 503 = capability dark here (check
/api/capabilities); 429 = rate-limited, back off.
Full walkthrough with curl examples: docs/AGENT_GUIDE_MY_COMPUTER.md in this repo.

## The CLIs (external, agent-facing)
Two tools. Each has several names across GitHub / install — they are the SAME binary.

### browser-agent  (aka browser-cli; served as `browseragent`)
- **What it's for:** hands-and-eyes for a browser — drives Chrome/Firefox over CDP with intent verbs
  (click/perceive/form_fill). Web automation, form-filling, scraping, multi-tab flows, and driving a
  hosted `*.browser.ab0t.com` browser sandbox.
- **Source (GitHub):** https://github.com/ab0t-com/browser-agent
- **Install:** `curl -fsSL https://sandbox.service.ab0t.com/cli/browseragent/install.sh | sh`
  (redirects to the repo's installer; checksum-verified)
- **Docs/skills:** GET /cli/browseragent/llm.txt · GET /cli/browseragent/skills

### computer-agent  (aka computer-cli; served as `desktopagent`)
- **What it's for:** hands for a whole Linux machine — terminal, filesystem, and GUI/RPA
  (screenshot/click/type/OCR, workflows, fleet) on a cloud XFCE desktop via `/api/desktops`.
- **Source (GitHub):** https://github.com/ab0t-com/computer-cli
- **Install:** `curl -fsSL https://sandbox.service.ab0t.com/cli/desktopagent/install.sh | sh`
  (redirects to the repo's installer; checksum-verified)
- **Docs/skills:** GET /cli/desktopagent/llm.txt · GET /cli/desktopagent/skills

Each CLI ships its own llms.txt and skills — read those next once you've picked one.
(Internal components such as the host-side computer-manager and the novaterm terminal are not
agent entry points and are intentionally not listed here.)

## Map
- GET /openapi.json        — the typed API contract (source of truth)
- GET /cli                 — list the CLIs this service serves (name, version, install)
- GET /cli/{name}          — info + per-platform downloads for one CLI
- GET /cli/{name}/install.sh — installer (sha256-verified)
- GET /cli/{name}/llm.txt  — that CLI's own agent doc (read it next)
- GET /cli/{name}/skills   — downloadable agent skills for that CLI
- /documentation           — human/agent usage guide

## Key facts an agent should internalize
- Which CLI: web pages -> browser-agent; a whole Linux machine/GUI -> computer-agent.
- Auth: send X-API-Key: ab0t_sk_... on every call; the JWT is only for minting keys; 401/403 = bad/expired/under-scoped credential.
- Onboarding has a multi-minute async window — a fresh account's first key mint 403s until perms provision; poll, don't give up.
- Multi-tenant: you only see your own org's resources; scope keys to least privilege.
- --json / -o json is available on CLI commands for machine-readable output.
- The *.ab0t.com hosts (sandbox.service, auth.service) are the product's public endpoints, not secrets.