Setup & Scripts

Four ways to run code in a Box, 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
Pre-commit hooks	Before each commit in that repository	Linting, tests, blocking bad commits
`--setup-file`	Once at start, per Box, in the background	A one-off script that differs between Boxes
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 Box so it is already installed when the Box starts.

Repository setup scripts

Attached to a repository in Dashboard > Environment. Runs once when the Box 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 Box is not usable until it finishes. A blocking script delays the Box reaching ready; a non-blocking one runs alongside everything else.

Pre-commit hooks

Also per repository, run before each commit made in that repository. Mark a hook blocking to fail the commit when the hook fails.

#!/bin/bash
npm run lint

Talking back to the Box

Setup scripts and hooks can both steer the agent running in the Box:

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

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

#!/bin/bash
npm run lint || queuePrompt "lint failed, fix the errors then commit again"

Per-Box setup file

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

box new --setup-file ./setup.sh

It runs in the background once the Box is ready and never delays ready. Watch it with box 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.

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

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

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

from ascii_box_sdk.models.command_request import CommandRequest

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

Wait for the Box to reach ready first; earlier calls are refused with a retryable box_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 Box yet, use SSH instead. It streams stdin, stdout and stderr, so nothing has to be copied to a temporary path first:

box 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

​Pre-commit hooks

​Talking back to the Box

​Per-Box setup file

​Driving setup from your code

​Related

Repository setup scripts

Pre-commit hooks

Talking back to the Box

Per-Box setup file

Driving setup from your code

Related