CLI reference
froog login | Log in: shows a code and opens the dashboard, where you type the code and approve it (on a remote machine, open the printed link anywhere). Then registers your SSH public key. --paste asks for an API key from the dashboard instead, and --key KEY or a key on stdin works for scripts. |
froog new [NAME] | Start a sandbox. --os ubuntu|debian|omarchy, --size, --ttl 4h (auto-stop that long after each start, default 1h, at most 30d), --no-auto-stop, --count N, --no-wait, --setup-file FILE, --no-environment, -e KEY=VALUE, --host PORT[:public] (a URL for a port), --file PATH=LOCAL (written before it's ready), --repo URL[#BRANCH] and --repo-dir DIR (a repo for this sandbox), --max-lifetime 2h (stop that long after each start), --delete-after 1d (delete after staying stopped that long), --expires 3h (delete that long after creation, whatever its state), --auto-start (start on a URL request or an API call while stopped), --environment NAME (one of your environments), --visibility shared|private (in an organization), --from SAVED|fsh_… (a saved snapshot, or a share code, --from-share CODE too, from a share code it starts without your environment unless you pass --environment NAME). |
froog run -- CMD | A new sandbox with this folder pushed to it: run the command, print the cost, delete the sandbox, exit with the command's code (Ctrl-C deletes it too). --push DIR, --no-push, --cwd DIR, --timeout SECS (exit 124), --from SAVED, --size, -e KEY=VALUE, --no-env, --keep (keep it, with snapshots, until its 15-minute auto-stop), --json. See one-off runs. |
froog push NAME [DIR] | Upload a folder (default: this one) to ~/FOLDER: git-tracked and not-ignored files. --to PATH puts it elsewhere. |
froog list · froog status NAME | Show sandboxes, with what each cost this billing period. --label KEY[=VALUE], --prefix and --state filter the list. |
froog label NAME KEY=VALUE KEY- | Set labels, or remove one with KEY-. new and fork take --label KEY=VALUE. |
froog ssh NAME [-- CMD] | Open a shell, or run a command over SSH. |
froog scp SRC DEST | Copy files: froog scp ./f box:~/ or froog scp box:~/f ., with -r for directories. |
froog exec NAME -- CMD | Run a command through the API (no SSH needed), printing its output as it arrives. --timeout SECS (up to 3600, past it the command is stopped and froog exec exits 124). --detach runs it in the background, and --timeout 0 streams a background run to the end. --cwd DIR, -e KEY=VALUE for this command only. A pipe or file on stdin is sent as the command's input (up to 1 MiB). --no-stdin skips it. |
froog jobs NAME · froog logs NAME JOB [-f] · froog kill NAME JOB · froog stdin NAME JOB [TEXT] [--close] | List, read or follow, and stop background commands. Write to the input of one started with --detach --stdin-open. |
froog wait NAME --port P | Wait until something listens on the port inside the sandbox. --timeout 2m (default 60s, at most 10m). Exits 1 on a timeout. |
froog audit | The account's audit log, newest first. --limit N, --cursor C for older entries, --action A (repeat), --sandbox NAME, --export csv|ndjson for everything as a file. |
froog info NAME | Everything about one sandbox: state, address, auto-stop timer, last reboot, disk use, a refused stop, disk retention, setup status, cost this period, snapshots, public URLs. (froog status NAME does the same.) |
froog status [--check] | API health, the signed-in account, and where the config and CLI live. --check exits 1 when not signed in or the API can't be reached. |
froog telemetry [set URL -H K=V | unset] | OpenTelemetry export of metrics and events. |
froog data-retention | Show the account's data controls. froog new --no-snapshots / --no-monitoring set them per sandbox. |
froog feedback "TEXT" | Send feedback to the froog team (or pipe it in). Replies go to your account email. 5 a minute, 30 a day. |
froog api-key list|create|rotate|revoke|actions | API keys with scopes: create NAME --preset read-only|full-sandbox|ci|admin or --actions, --sandbox NAME, --label KEY=VALUE, --env NAME (only that environment's sandboxes), --ttl 30d|never. |
froog history NAME [CMD_ID] [--stderr] [-f] · froog ps NAME [--history [--since 6h]] | Past commands and their output (90 days, also while stopped) and processes, busiest first (with --history, the samples taken every 30 seconds, kept 7 days, with --records [--running], every process seen, kept 72 hours). |
froog alerts [on|off KIND...] | Which emails the account gets (disk, stop_refused, unresponsive, rebuilt, plan_nudge, billing), and auto-rebuild. |
froog metrics NAME | CPU, memory, disk and network of a running sandbox, read now. --history [--since 6h]: the 30-second samples kept 7 days. |
froog prompt NAME "TEXT" | Give a coding agent a task and print its work until the turn ends (exit 0 done, 1 failed, 130 interrupted). --agent claude|codex|gemini|opencode|pi|amp|cursor|prime|kimi|mistral, --model, --effort, --fast, --new, --conversation ID, --attach FILE, --detach, --timeout SECS, --list-models. |
froog conversations NAME [ID] | Agent conversations, or one's turns. --delete. |
froog events NAME | What the agents did. --follow, --conversation ID. |
froog steer NAME "TEXT" | Send a message to the running turn. --conversation ID. |
froog interrupt NAME | Stop running turns, cancel queued prompts. --conversation ID. |
froog ai | AI credentials (details): proxy [on|off], profiles, profile-new|profile-set|profile-rm, key-add PROVIDER|NAME [--base-url URL [--secret-header H [--secret-prefix P]|--secret-query Q]] [--profile P], key-rm ID, switch ID, env ENV [PROFILE], use NAME PROFILE, usage [NAME] [--days N], block|unblock NAME|--all. |
froog subscriptions | Claude and ChatGPT sign-ins: login claude|chatgpt --sandbox NAME, logout claude|chatgpt. |
froog host NAME [PORT] [--public] [--subdomain S] [--title T] [--rm] | An HTTPS URL for a port, private (with a token) unless --public. Without PORT, list them. |
froog port open|close NAME PORT[/tcp|udp], froog port list NAME | Open or close a raw port on the sandbox's IPv6 address (TCP unless /udp), kept across stops and starts. See Network. |
froog url-token create|list|revoke NAME PORT | Extra tokens for a private URL, one per viewer: create --ttl 2h --label alice prints the URL with it, revoke NAME PORT ID cuts one off. |
froog forward NAME PORT | Reach a port of the sandbox on localhost through SSH, e.g. froog forward box 3000, or 8080:3000 for local:remote. --bind 0.0.0.0 (or another local address) lets other machines on your network reach it. --reverse: a port on this computer inside the sandbox instead (--bind then sets the address inside the sandbox). Reconnects when the sandbox comes back on a new address. The sandbox still stops at its auto-stop deadline. |
froog ssh-config [NAME…] | Add your sandboxes (default: all) to ~/.ssh/config as froog-NAME, for plain ssh, scp and VS Code or Cursor. Each connection finds the current address and starts a stopped sandbox. --no-start, --print, --file PATH, --remove. See VS Code and Cursor. |
froog desktop NAME | Open the desktop in your browser. --theme dark|light, --print prints the link, and --tunnel uses an SSH tunnel instead. |
froog browser NAME | Open only Chrome (no desktop) in your browser. --profile /abs/dir picks the Chrome profile, and --print and --theme work as for desktop. |
froog snapshot NAME | Save a snapshot. --name LABEL names it, --delete SNAPSHOT deletes one. |
froog snapshot share|shares|unshare SAVED | Share codes of a saved snapshot: make one (shown once), list them, revoke one (unshare SAVED shr_…). |
froog snapshot ls|pull SNAPSHOT [PATH] | Files inside a snapshot (a saved snapshot's name or SANDBOX@SNAPSHOT), without starting it. pull -o DIR. Default all of ~. |
froog snapshots [NAME] | A sandbox's snapshots, or without NAME, your saved snapshots. --rm SAVED removes a saved snapshot. |
froog fork NAME[@SNAP] NEW | New sandbox from a snapshot (default: the current state). --count N, --size, -e KEY=VALUE (on top of the source's own variables), --ttl 1h (default: the source's auto-stop timer), --no-snapshots (a stop erases the copy), --no-environment (the copy runs without your environment, your logins removed), --environment NAME (that environment's latest version instead of the source's). |
froog restore NAME@SNAP | Roll back in place. NAME@latest uses the newest snapshot, e.g. to recover a sandbox in the error state. |
froog stop NAME · --all · --force | Run ~/.froog/pre-stop, snapshot and stop billing. --force stops even if the snapshot fails, keeping the last good one (see Stopping safely). --no-wait prints the stop's id, and froog stop --status ID shows it (pending, failing, completed, superseded or failed). |
froog start NAME | Resume from the latest snapshot. --size starts it at another size, --ttl 2h sets a new auto-stop timer, counted from this start (0 for none), --no-environment boots without your environment, your logins removed (--environment with it again, --environment NAME onto that environment's latest version), -e KEY=VALUE adds a variable of its own. These stay for later starts. |
froog rename NAME NEW | Rename a sandbox (its hostname changes on its next start). |
froog extend NAME [TTL] | Move the auto-stop: --hours 12 (or 12h) stops it 12 hours from now, and later starts get 12 hours too. --no-auto-stop (or 0) turns it off. --max-lifetime and --delete-after change those (0 removes them), and --expires 1h sets the deadline to an hour from now (0 removes it). --auto-start / --no-auto-start turn auto-start on or off. |
froog delete NAME | Delete a sandbox and its automatic snapshots. Its saved snapshots stay (froog snapshots). -y skips the prompt. |
froog mcp | An MCP server on stdio with this CLI's login, for Claude Code, Codex, Cursor and Claude Desktop: claude mcp add froog -- froog mcp. --docs: the docs MCP server instead (no login). |
froog inbox create|list|rm|messages|read|wait|attach|detach|billing | Tokenmail inboxes for agents, $2 a month each: wait ADDRESS --code prints the next one-time code (--link: the verification link). |
froog webhooks list|add|update|deliveries|rm|rotate|test | Signed notifications of sandbox state changes, and their delivery log. |
froog env list|set|rm | Environment variables every new sandbox gets. set NAME without a value reads it from stdin. |
froog environment show|add-repo|rm-repo|repo-setup|setup|add-file|rm-file | Repos, secret files and setup scripts for every new sandbox. Set the script with setup FILE (or - for stdin, --clear to remove). repo-setup REPO FILE for one repo. --env NAME works on another environment than the default. |
froog environment list|create|rm|rename|default|versions|upgrade | Named environments and their versions: create NAME [--copy-from ENV] [--default], upgrade NAME [--sandbox S] (also froog env upgrade NAME). |
froog keys list|add|rm | Manage the SSH keys allowed into your sandboxes. |
froog github · connect · repos · token-repos [OWNER/NAME…] · disconnect ID | The GitHub connection: install the app, list repositories, limit the token in sandboxes, unlink. |
froog ci · job ID · logs ID · public on|off [--users a,b] | GitHub Actions jobs on froog: setup, stats and jobs (--repo, --state, --limit), one job, its log, public repositories. |
froog connections · add-email ADDR · primary ID · rm ID | Sign-in methods on your account. |
froog usage [--month YYYY-MM] · froog usage NAME [--since T] [--until T] | This billing period: hours and cost per size, snapshots, the total, what your plan covers and what's past it. --month: a past calendar month at list prices. With NAME: that sandbox's hours and cost, this period or between --since and --until (YYYY-MM-DD, YYYY-MM-DDTHH:MM in UTC, unix seconds, or a time ago like 7d). |
froog limits | Sandboxes at once (from your plan), sizes, the free trial's days and hours used, and start limits. |
froog billing | Your plan, its renewal, this period's usage against what's included, the wallet and the rates. With no plan, it lists the plans. |
froog billing plan 10|20|50|100 | Choose a plan. The first opens Stripe Checkout in your browser and waits. Later changes apply at once. |
froog billing cancel [--keep-disks] · end-trial · portal | End the plan at the end of the period (--keep-disks: pause, keeping disks 90 days) · end the free trial now and start paying · change the card or download invoices. |
froog billing extra-starts on|off | Pay from the wallet for starts past the start limits instead of being refused. |
froog wallet · froog wallet pay N · froog wallet quote N · froog wallet auto N|off | The wallet balance and auto top-up · add N dollars ($15 minimum, with the bonus from $200) · what N dollars adds with the bonus · top up N dollars when it runs low, or stop. |
froog onboard [--yes] | A guided first run: sign in, SSH key, agent keys, a first sandbox (a plan is asked for only then), a first prompt. Skips what's done. |
froog dashboard | Open the dashboard signed in, with a link that works once, for 15 minutes: the page asks "Continue as EMAIL?" first. Needs a full-access key. |
froog org · list · create NAME · switch ORG|personal | Organizations: the workspace in scope · yours, the active one marked · a new one (you own it) · the one commands act in from now on. --org ORG (or FROOG_ORG) on any command acts in another for that command only. |
froog org members · invite EMAIL [--admin] · revoke-invite ID · accept TOKEN · remove EMAIL · leave | Members and pending invites · invite by email · revoke an invite · join with an invite link · remove a member · leave. |
froog org role EMAIL admin|member · cap EMAIL [--running N] [--usage USD] · transfer EMAIL | Roles (owner) · per-member caps (0 removes one) · make another member the owner. |
froog org seats [N] · default-visibility [shared|private] · rename NAME · delete [--yes] | Seats bought · whether new sandboxes start shared or private · rename · delete (the last member, with no sandboxes). |
froog share NAME · froog unshare NAME | Let every member use one of your organization sandboxes · make it private again. |
froog account · froog account close [--yes] · froog account reopen | Your account · close it (asks you to type its email) · reopen it within 30 days. |
froog deletion status ID | A deletion operation (dop_…). |
froog ssh and froog exec without a name use the last sandbox you created or started on this computer. Inside a sandbox, self means that sandbox (froog host self 3000, froog snapshot self --name ready), and ssh, exec, stop and start without a name use it. The API knows it too: with the in-sandbox key (in ~/.config/froog/config.json), /v1/sandboxes/self/… is that sandbox, and so is "name": "self" in an MCP tool call, so curl, the SDKs (froog.sandboxes.get("self")) and agents inside a sandbox don't need its name. With any other key, self is 400. No sandbox can be named self. froog completions bash|zsh|fish prints shell completions, froog self-update installs the newest CLI, and froog logout forgets the saved key.
Every command accepts --json for machine-readable output. The CLI reads FROOG_API_KEY and FROOG_API_URL from the environment, which overrides ~/.config/froog/config.json.