Setup & Scripts

Three ways to run code in a sandbox, from the one that needs no code of your own to the one you drive entirely from your backend. They stack, so most setups use more than one.

	Runs	Best for
Repository setup script	Once at start, in one repository’s folder	`npm install`, migrations, anything per repository
`--setup-file`	Once at start, per sandbox, in the background	A one-off script that differs between sandboxes
Commands from your code	Whenever you call	Orchestration your backend controls

For anything heavy or slow, do not script it at all: bake it into a template sandbox so it is already installed when the sandbox starts.

Repository setup scripts

Attached to a repository in Dashboard > Environment. Runs once when the sandbox starts, inside that repository’s folder, with your environment’s variables and secret files already in place.

#!/bin/bash
npm install
npm run db:migrate

Mark it blocking when the sandbox is not usable until it finishes. A blocking script delays the sandbox reaching ready; a non-blocking one runs alongside everything else.

Talking back to the sandbox

Setup scripts can steer the agent running in the Sandbox:

Call	Effect
`queuePrompt "your instruction"`	Sends a message to the sandbox, as if you had typed it
`stopAgent`	Halts the agent

That turns a failing step into an instruction rather than a dead end:

#!/bin/bash
npm install || queuePrompt "npm install failed, fix the install then continue"

Per-Sandbox setup file

When the work differs from Boat to Boat, pass a local script at create time. Up to 64KB, UTF-8.

boat new --setup-file ./setup.sh

It runs in the background once the sandbox is ready and never delays ready. Watch it with boat info:

Field	Values
`setupStatus`	`pending`, `running`, `done`, `failed`
`setupError`	Why it failed

Driving setup from your code

Configure secrets in the environment first, then run whatever you need. The script reads normal environment variables and the secret files at their configured paths, so nothing sensitive passes through the command line.

sandbox_id="$(boat new --json | jq -r 'select(.event == "ready") | .id')"
boat exec "$sandbox_id" --cwd my-repo "bash ./setup.sh"

curl -sS -X POST "$BOAT_API_BASE/sandboxes/$BOAT_ID/commands" \
  -H "Authorization: Bearer $BOAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command":"bash -lc ./setup.sh","cwd":"my-repo","timeoutSeconds":60}'

await sandbox.command({
  sandboxId,
  commandRequest: {
    command: "bash -lc './setup.sh'",
    cwd: "my-repo",
    timeoutSeconds: 60,
  },
});

from boat_sdk.models.command_request import CommandRequest

sandbox.command(
    sandbox_id,
    CommandRequest(command="bash -lc './setup.sh'", cwd="my-repo", timeout_seconds=60),
)

Wait for the sandbox to reach ready first; earlier calls are refused with a retryable boat_starting. Synchronous commands cap at 600 seconds, so anything longer should detach and be polled. See Long-Running Tasks. To pipe a script that is not on the sandbox yet, use SSH instead. It streams stdin, stdout and stderr, so nothing has to be copied to a temporary path first:

boat ssh bx_f7k2q9hd -- bash -s < ./setup.sh

On Windows, run this from Node, Python, WSL, Git Bash, or cmd.exe. Native PowerShell pipelines can keep stdin open for native executables, which hangs the command.

​Repository setup scripts

​Talking back to the sandbox

​Per-Sandbox setup file

​Driving setup from your code

​Related

Repository setup scripts

Talking back to the sandbox

Per-Sandbox setup file

Driving setup from your code

Related