> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup & Scripts

> Run code inside a Sandbox: setup scripts and driving setup from your own program.

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](#repository-setup-scripts)     | Once at start, in one repository's folder     | `npm install`, migrations, anything per repository |
| [`--setup-file`](#per-sandbox-setup-file)                | Once at start, per sandbox, in the background | A one-off script that differs between sandboxes    |
| [Commands from your code](#driving-setup-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](/snapshots#template-sandboxes) so it is already installed when the sandbox starts.

## Repository setup scripts

Attached to a repository in [Dashboard > Environment](https://boat.dev/dashboard?tab=environment). Runs once when the sandbox starts, inside that repository's folder, with your environment's variables and secret files already in place.

```bash theme={null}
#!/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:

```bash theme={null}
#!/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.

```bash theme={null}
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.

<CodeGroup>
  ```bash CLI theme={null}
  sandbox_id="$(boat new --json | jq -r 'select(.event == "ready") | .id')"
  boat exec "$sandbox_id" --cwd my-repo "bash ./setup.sh"
  ```

  ```bash curl theme={null}
  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}'
  ```

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

  ```python Python theme={null}
  from boat_sdk.models.command_request import CommandRequest

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

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](/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:

```bash theme={null}
boat ssh bx_f7k2q9hd -- bash -s < ./setup.sh
```

<Note>
  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.
</Note>

## Related

* [Environments](/environments)
* [Snapshots & Copies](/snapshots)
* [Long-Running Tasks](/long-running-tasks)
* [SSH Access](/ssh-access)