---
name: froog
description: Run builds, tests, untrusted code, Docker, long jobs, servers with public URLs, or other coding agents in froog cloud sandboxes (full Linux VMs) with the `froog` CLI instead of on this computer. Use when the user mentions froog or sandboxes/VMs, when a task needs isolation, a clean Linux machine, Docker, lots of CPU, or work that should keep running after this session.
---

# froog cloud sandboxes

Each sandbox is a full Ubuntu 24.04 (or Ubuntu 26.04, Debian 13 or Omarchy) VM with its own kernel, SSH, Docker, passwordless sudo and the usual toolchains (Node, Python/uv, Go, Rust, coding agents). You drive it with the `froog` CLI. Full docs: https://froogcorp.com/llms-full.txt (index: https://froogcorp.com/llms.txt).

## Before you start

- `froog list` checks the CLI is installed and signed in. If not: install with `curl -fsSL https://froogcorp.com/install | sh`, then sign in with `echo "$FROOG_API_KEY" | froog login` (or set `FROOG_API_KEY`). Ask the user for a key from https://froogcorp.com/dashboard/ if there is none.
- Prices and limits change: run `froog limits`, `froog usage` and `froog billing`. Never quote prices from memory. Running time is billed per second, and starting a sandbox needs a plan. If a start fails with `subscription_required` or `insufficient_funds`, tell the user: `froog billing plan 20` chooses a plan, `froog wallet pay 15` adds money.
- Always pass the sandbox name explicitly. Names: lowercase letters, digits and dashes.
- Teams: `froog org` shows the workspace commands act in (personal, or an organization). If a sandbox the user mentions isn't in `froog list`, it may be in an organization: `froog org list`, then `froog --org NAME list`. Don't `froog org switch` without asking: it changes the user's default for every client.

## Everyday commands

```sh
froog new task-1                         # returns when SSH works (~1 min). --size small|default|large (xlarge coming soon), --os debian
                                         # --host 3000[:public] (a URL), --file app/.env=.env (written before ready)
                                         # --repo URL#branch (clone it in), --max-lifetime 2h, --delete-after 1d, --expires 3h (deleted then)
                                         # --auto-start (a URL request or an exec/file call starts it while stopped)
froog exec task-1 -- 'cd app && npm test'  # streams output, exits with the command's code. --timeout SECS (max 3600; 124 if hit)
froog exec task-1 --cwd app -e CI=1 -- npm test  # in ~/app, with a variable for this command only
git diff | froog exec task-1 --cwd app -- git apply  # a pipe or file becomes stdin (1 MiB; --no-stdin skips it)
froog run -- npm test                    # fresh sandbox + this folder, run, print the cost, delete. --push DIR, --timeout, --keep, --from, --size, --json
froog exec task-1 --detach -- 'npm run dev' # background job: prints JOB id
froog wait task-1 --port 3000            # until something listens on the port (--timeout 2m; exits 1 if not)
froog logs task-1 JOB -f                 # follow it. froog jobs task-1 lists, froog kill task-1 JOB stops
froog exec task-1 --timeout 0 -- ./long.sh  # background, but stream to the end
froog history task-1                     # every command run, 90 days, also while stopped
froog history task-1 CMD_ID [--stderr]   # its output
froog ps task-1                          # processes, busiest first. froog metrics task-1: CPU, memory, disk, network now (--history: the last 7 days)
froog push task-1                        # this folder to ~/FOLDER (git-tracked, not-ignored files). --to PATH
froog scp -r ./app task-1:app            # copy files (or git clone inside the sandbox)
froog host task-1 3000                   # HTTPS URL for a port (private: carries a token, --public for none)
froog url-token create task-1 3000 --ttl 2h --label alice  # a revocable token per viewer (list, revoke)
froog forward task-1 3000                # the port on localhost instead (--bind 0.0.0.0 for your network)
froog ssh-config task-1                  # ssh froog-task-1 / VS Code Remote-SSH, across starts
froog prompt task-1 "fix the failing tests" --agent claude|codex|gemini|opencode|pi|amp|cursor|prime|kimi|mistral
froog prompt task-1 "now add a test"     # same conversation (memory); --new for another, --conversation ID
froog steer task-1 "skip the e2e tests"   # message to the running turn; froog interrupt task-1 stops it
froog events task-1 --follow               # what the agents do; froog conversations task-1
froog stop task-1                        # snapshot the disk, stop billing. froog start task-1 resumes
froog start task-1 --ttl 2h -e KEY=VALUE  # resume with a new auto-stop timer or variables (--no-environment: none of yours)
froog fork task-1 task-2                 # a copy from its latest snapshot (task-1@LABEL: from a saved one). -e KEY=VALUE, --ttl, --no-snapshots
froog delete task-1 --yes                # erase it (its saved snapshots stay)
```

`--json` on any command prints JSON instead of text.

## Good practice

- Templates: `froog snapshot task-1 --name web-stack` once, then `froog new app-1 --from web-stack` (saved snapshots outlive their sandbox, and `froog snapshots` lists them).
- Look inside a snapshot without starting it: `froog snapshot ls task-1@latest app`, `froog snapshot pull web-stack ~/app -o ./app`. Give a saved snapshot to another account: `froog snapshot share web-stack` prints a code for `froog new --from fsh_…` (your logins are removed from their copy; it starts without their environment unless they add `--environment NAME`).
- Environments: `froog new job --environment ci` picks one of your named environments; sandboxes stay on the environment version they started with until `froog environment upgrade ci`.
- One sandbox per task. Fork a prepared one (`froog snapshot task-1 --name ready`, then `froog fork task-1@ready try --count 5` makes try-1 … try-5) to run many in parallel.
- Prefer `froog exec` for short commands and `--detach` + `froog logs -f` for anything over a few minutes or that never ends (servers).
- Every sandbox auto-stops 1 hour after each start by default, busy or not (a running `froog prompt` holds it off): `froog new NAME --ttl 4h` (at most 30d), `froog new NAME --no-auto-stop`, `froog extend NAME --hours 12` (12 hours from now), `froog extend NAME --no-auto-stop`. Stopped disks are kept 14 days.
- Private GitHub repos: if `froog github` shows a connection, sandboxes started with the environment already have git and gh credentials for its repositories (a one-hour token, renewed by the git credential helper). Don't paste tokens into URLs.
- Agent keys: `froog env set ANTHROPIC_API_KEY` (or `OPENAI_API_KEY`, …) once puts them in every new sandbox. A prompt with no key fails with `provider_not_configured` (exit 78).
- Keep keys out of sandboxes: `froog ai proxy on` gives sandboxes placeholder keys (`froog-ph-…`) and proxy base URLs; `froog ai key-add anthropic` adds accounts (switched when one hits a limit), `froog ai usage [NAME]` shows tokens and estimated cost, `froog ai block NAME` stops a sandbox's AI requests.
- Email: `froog inbox create --username NAME` makes an address on froogmail.com ($2 a month, receive-only; the first one opens Stripe Checkout for the user), then `froog inbox wait ADDRESS --code` prints the one-time code (`--link`: the verification link). A sandbox with an inbox attached (`--sandbox NAME`) has it in `$FROOG_EMAIL`. Don't buy inboxes without the user's go-ahead. Only for services that allow agents; at a CAPTCHA, stop and ask the user.
- Clean up: stop or delete sandboxes you started when the task is done, unless the user wants them kept.

## MCP tools instead of the CLI

If this agent has froog's MCP tools (`create_sandbox`, `exec`, `start_job` + `job_logs` for long commands, `fork_sandbox`, `read_file`, …), use them the same way: always pass the sandbox name, and stop or delete what you made. `delete_sandbox` needs `confirm: true`. To add them: `claude mcp add froog -- froog mcp` (uses the CLI's login), or the hosted server https://api.froogcorp.com/mcp with `Authorization: Bearer $FROOG_API_KEY`. Other clients: https://froogcorp.com/docs/mcp/

For exact flags, limits and error codes, search the docs: the `froog-docs` MCP server (`claude mcp add --transport http froog-docs https://api.froogcorp.com/docs-mcp`, tools `search_docs` and `read_docs`) or https://froogcorp.com/llms-full.txt.