---
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 Debian 13) 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://froog.tech/llms-full.txt (index: https://froog.tech/llms.txt).

## Before you start

- `froog list` checks the CLI is installed and signed in. If not: install with `curl -fsSL https://froog.tech/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://froog.tech/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.

## Everyday commands

```sh
froog new task-1                         # returns when SSH works (~1 min). --size small|default|large, --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
                                         # --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. --keep, --from, --size
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
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 prompt task-1 "fix the failing tests" --agent claude|codex|gemini|opencode|pi|amp|cursor
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).
- 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.
- 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).
- 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`, `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.froog.tech/mcp with `Authorization: Bearer $FROOG_API_KEY`. Other clients: https://froog.tech/docs/#mcp