Docs navigation
Agent

Entrypoint

Entrypoint is a bash script that runs inside the agent's sandbox after secrets load and before the runtime boots. Use it to prepare the environment the agent needs before it starts working.

Sandbox startup comes first
When an agent's sandbox was paused, Brainbase wakes it before the entrypoint runs: sandbox access first, then setup, then the runtime. Temporary sandbox transitions are retried automatically during wake-up, so a short delay before setup starts is normal. If the sandbox cannot be started, the task fails during startup and the entrypoint does not run.
How to use entrypoint
UI
  1. 01Open the agent's Entrypoint area.
  2. 02Write the bash setup script.
  3. 03Save your changes.
  4. 04Run a task and confirm the runtime has the expected dependencies.

What entrypoint is for

  • Install dependencies: Run package managers, install system packages, or build generated assets.
  • Clone or prepare code: Fetch a repository, check out a branch, or create folders the agent expects.
  • Configure the sandbox: Write config files, set permissions, or warm caches before the harness starts.

Write an entrypoint

Keep the script idempotent: it should be safe to run more than once. In the UI, leaving the editor empty means the agent has no entrypoint. In the CLI manifest, set exactly one of entrypoint.file, entrypoint.commands, or entrypoint.text.

Time limit and failures
The entrypoint has a 600-second budget. A script that runs longer is stopped and the task fails during startup, with the last lines of its output in the failure message. A script that exits with a non-zero status does not stop the task: the exit is recorded, and the agent still starts, so check that setup actually succeeded. The script's output is saved to .brainbase/entrypoint.log in the sandbox.
entrypoint.shbash
set -euo pipefail

if [ ! -d repo ]; then
  git clone https://github.com/acme/internal-tools.git repo
fi

cd repo
npm ci
npm run build

Use secrets

Secrets are available before the entrypoint runs, so the script can use them for package registries, private repositories, or setup commands. Read them from environment variables and avoid printing them to logs.

entrypoint.shbash
set -euo pipefail

git clone "https://oauth2:${GITHUB_TOKEN}@github.com/acme/private-repo.git" repo
cd repo
npm ci

Best practices

  • Keep setup fast; slow entrypoints delay every task startup.
  • Make commands repeatable and safe if the sandbox already has the file or package.
  • Use Secrets for tokens and private configuration.
  • Avoid destructive commands unless the agent needs a clean environment every time.
  • Prefer pinned package versions for predictable behavior.