Recipes

A coding agent on your repo

Set things up once for your account, then every new sandbox starts with the repo cloned, dependencies installed and the agent's key in place:

$ froog env set ANTHROPIC_API_KEY                        # for Claude Code
$ froog env set GH_TOKEN                                 # a GitHub token that can push; git and gh use it
$ froog environment add-file .gitconfig ~/.gitconfig     # your name and email for commits
$ froog environment add-repo https://github.com/you/app
$ echo 'cd ~/app && npm ci' | froog environment setup -

$ froog new fix-login
$ froog jobs fix-login                                   # the setup job clones and installs; wait until it has exited
$ froog prompt fix-login "In ~/app: fix the login redirect bug, run the tests, commit on a new branch, push it and open a pull request with gh"
$ froog stop fix-login                                   # or froog delete fix-login -y

froog prompt follows the agent while your terminal stays connected. The agent keeps working if you disconnect (--detach doesn't wait at all), and froog events NAME shows what it did. You can also run an agent as a background command and read its raw output later, even after the sandbox has stopped (command history):

$ froog exec fix-login --detach -- 'cd ~/app && claude -p "fix the login redirect bug and open a PR" --dangerously-skip-permissions'
$ froog logs fix-login JOB -f

The agent has root in its sandbox and can read every variable and secret file you gave it, so give it tokens that can do only what the task needs (for example a fine-grained GitHub token for one repo).

Parallel agents

Prepare one sandbox, save it, start several copies, and give each one a task (or the same task with different agents):

$ froog new base
$ froog exec base -- 'git clone https://github.com/you/app && cd app && npm ci && npm test'
$ froog snapshot base --name app-ready
$ froog new try --from app-ready --count 3               # try-1, try-2, try-3

$ froog prompt try-1 "In ~/app: make the search page faster" < /dev/null > try-1.log 2>&1 &
$ froog prompt try-2 "In ~/app: make the search page faster" --agent codex < /dev/null > try-2.log 2>&1 &
$ froog prompt try-3 "In ~/app: make the search page faster" --agent gemini < /dev/null > try-3.log 2>&1 &
$ wait

$ froog exec try-2 -- 'cd app && git diff --stat && npm test'   # compare
$ froog delete try-1 -y && froog delete try-3 -y                # keep the best

Each copy has its own disk and starts with your variables, so the agents' keys are there. Programs don't carry over from the snapshot: start servers again in each copy. How many run at once depends on your plan (2, 5 or 10). Forking a running sandbox (froog fork base try --count 3) works too, without saving a snapshot first. Agents that use the desktop share one screen per sandbox, so give each GUI task its own sandbox.