Docs · Agents

Build a platform: a sandbox per user

Products can give each of their users (or each project) a sandbox: persistent files, a coding agent that works inside it, a private preview URL. The terms allow it. The pieces:

  1. A key for your backend. froog api-key create backend --preset ci creates, starts, forks and deletes only what it created, and can't touch billing or other keys. Store it as FROOG_API_KEY. For a component that serves one user, make a key limited to that user's sandbox: --sandbox user-42.
  2. Nothing of yours in user sandboxes. Create them with "environment": false (no account variables, repos, secret files or in-sandbox froog key), and give each one what it needs with its own variables: the user's API keys, a tenant id.
    POST /v1/sandboxes
    {"name": "user-42", "from": "web-stack", "environment": false,
     "env": {"TENANT_ID": "42", "ANTHROPIC_API_KEY": "<the user's key>"}}
  3. A template. Install your stack once in a sandbox and save it (froog snapshot base --name web-stack). Every user's sandbox starts from it with "from": "web-stack". Put house rules for the agents (AGENTS.md, CLAUDE.md, skills, MCP servers) in it too.
  4. Know when it's ready. Create answers 202 at once. The sandbox is usable when its state is running (poll GET /v1/sandboxes/{name}, or take the sandbox.running webhook).
  5. Run the agent. POST /v1/sandboxes/{name}/prompts {"prompt", "agent", "model"} queues a task for one of ten harnesses with the user's keys (a missing key answers 400 provider_not_configured). Stream its events into your UI with Accept: text/event-stream. Later prompts continue the same conversation, and /steer and /interrupt map to your UI's send and stop buttons.
  6. Show the result. POST /urls {"port": 3000} gives a private preview URL (it carries a token, so treat it like a password). Use "public": true to embed it in an iframe on your site, since browsers may block the private URL's cookie there. Hand files to the user's browser with signed download and upload URLs.
  7. Keep only what you must. Monitoring off keeps no command history, and zero data retention erases each sandbox at stop.

Patterns and cost

Sandboxes are paid by the month: each slot in your setup runs one sandbox 24/7 ($5 a month for default). So:

  • Always on, one sandbox per project or per user: the simplest, one slot each. A user's projects can share one sandbox, each in its own folder on its own port.
  • More users than slots: stop a user's sandbox when they leave (its disk is kept 14 days; save a snapshot to keep it longer) and start it when they return, in about 15 seconds: a slot holds whichever sandboxes are running. An auto-stop timer (ttl_secs, froog extend NAME --hours 2) does it for you. Processes don't survive a stop: run your dev server from the setup script.
  • Disposable per task: start from the template, run, read the output, delete; the slot is free again for the next one.

Starts are limited to 20 a minute, 100 an hour and 500 a day per account (more with a bigger setup): GET /v1/limits shows where you are.