Skip to content

Prepare a runtime environment

Run submissions to Docker targets accept an environment field alongside runtime:

{
  "environment": {
    "setup": "apt-get update && apt-get install -y jq",
    "startup": "npm ci",
    "variables": { "CI": "true" },
    "contextRepositories": [
      { "repository": "acme/shared-library", "branch": "main" },
      { "repository": "acme/api-contracts" }
    ]
  }
}

Profiles contain graph and agent settings and have no environment reference. Supply the concrete definition when submitting a run. With the CLI, put the contents of environment above into a JSON file and pass --environment FILE alongside your profile. --no-environment sends an explicit empty definition ({}), which bypasses defaults on hosts that provide them. Omitting both flags leaves selection to the host. Direct Docker uses the base environment when none is supplied. Stack manifests also accept a top-level environment; the definition applies to each run in that stack, while omission allows the host to resolve each repository's default.

Hosts may provide saved environments and choose repository defaults before accepting a run. zeroshot executes the resolved definition and preserves it for queued and resumed attempts; it does not store environment resources or interpret repository defaults. The local UI has no environment catalog or selector. Connection values come from the existing target connection mechanism and never belong in scripts or public variables. Only explicitly declared hook connections reach preparation; node connections remain independently declared. If installation needs private registry access, add "connections": { "package-registry": ["NPM_TOKEN"] } to the definition. The CLI can collect hook credentials for a definition you supply. When a host selects a default, its connection store must supply those credentials; the CLI does not inspect saved environments to discover additional secrets in your shell.

Read-only context repositories

contextRepositories lists up to 16 extra repositories that agents can inspect and build against. Each entry has a repository (GitHub owner/name or a credential-free HTTPS/SSH Git URL) and an optional branch. The CLI reads this list from --environment FILE and resolves each branch to an exact commit before submitting to a named target. An omitted branch uses the remote's default branch. Duplicate repositories and the run's own source repository are rejected. Context repositories must use the source repository's forge and be accessible with its existing source credential; there is no separate context credential.

Targets clone full history before the startup hook. The clones live outside the workspace at $ZEROSHOT_CONTEXT/<repository path>: for example, $ZEROSHOT_CONTEXT/acme/shared-library. Startup and every agent receive ZEROSHOT_CONTEXT; private agent guidance also lists the paths and pinned commits. Status, list and history retain the ordered pins as contextSources beside source.

When context repositories are requested, GIT_CONFIG_GLOBAL, GIT_CONFIG_PARAMETERS, and GIT_CONFIG_COUNT overrides in variables or hook/node connections are rejected before preparation. The target supplies exact-path Git trust for the supervisor-owned checkouts. Runs without context repositories keep their existing Git settings.

These checkouts are readable but cannot be modified or pushed by agents or startup hooks. For experiments, copy a repository into $TMPDIR, make the copy writable if your copy tool preserves read-only permissions, and edit/build there. Keep experimental copies outside the workspace: delivery commits the workspace, which still belongs to exactly one source repository. Copies have no source credentials and cannot authenticate a push.

Context repositories are excluded from checkpoints. Every allocation, including a resume or checkpoint restore, clones the original pinned commits again even if their branches have moved. An unavailable repository or commit stops preparation with context_checkout_unavailable before agents start. Cloning shares the existing preparation deadline. A host-selected default environment that lists context repositories also requires matching client pins; the target never resolves mutable branch tips on the client's behalf. Local runs reject context repositories, as they reject setup and startup hooks. Runs without context repositories receive no ZEROSHOT_CONTEXT.

Example: pinned Node and npm dependencies

For a repository with a committed package-lock.json, save this as setup.sh. It installs OS packages and Node 22.22.3, verifies the archive against the release's SHA-256 checksums, and exposes Node to every agent through $ZEROSHOT_TOOLS/bin:

set -euo pipefail
export DEBIAN_FRONTEND=noninteractive
apt-get update -qq
apt-get install -y --no-install-recommends jq sqlite3 xz-utils

case "$(uname -m)" in
  x86_64) arch=x64 ;;
  aarch64) arch=arm64 ;;
  *) echo 'Unsupported Node architecture' >&2; exit 1 ;;
esac
version=22.22.3
release="node-v$version-linux-$arch"
download=$(mktemp -d)
trap 'rm -rf "$download"' EXIT
curl -fsSL "https://nodejs.org/dist/v$version/$release.tar.xz" -o "$download/$release.tar.xz"
curl -fsSL "https://nodejs.org/dist/v$version/SHASUMS256.txt" -o "$download/SHASUMS256.txt"
(cd "$download" && sha256sum --check --ignore-missing SHASUMS256.txt)
tar -xJf "$download/$release.tar.xz" -C "$ZEROSHOT_TOOLS"
for tool in node npm npx; do
  ln -sfn "../$release/bin/$tool" "$ZEROSHOT_TOOLS/bin/$tool"
done
node --version

Save the workspace preparation as startup.sh. npm ci rebuilds node_modules from the lockfile, so this also works after restoring a workspace:

set -euo pipefail
test "$(node --version)" = v22.22.3
npm ci --no-audit --no-fund

On your machine, use jq to embed both scripts in a flat environment file, then submit it with your existing profile, task input file, and target:

jq -n --rawfile setup setup.sh --rawfile startup startup.sh \
  '{setup: $setup, startup: $startup, variables: {CI: "true"}}' > environment.json
zeroshot run --profile my-profile --target my-target \
  --environment environment.json --title "Fix the failing test" --input input.json

The file contains setup and startup directly; an inline run API request puts the same object in submission.environment, beside submission.runtime. Setup cannot read repository files because checkout has not happened yet. Startup can invoke a checked-in script, for example bash .zeroshot/startup.sh.

Lifecycle and installation conventions

Submission returns after admission and durable acceptance. While the run is admitted, setup runs as root before source checkout or workspace restoration. Startup then runs as the workspace user, with the checkout as its current directory. The graph starts only after both succeed. Watch run logs for phase progress and command output. Nonzero exits become environment_setup_failed or environment_startup_failed; a preparation deadline becomes environment_preparation_timeout. These stop the run without using any graph repair attempts. Force-stop works during preparation and waits for process cleanup before recording its terminal result.

Each hook uses Bash with errexit and pipefail and has fifteen minutes, inside one thirty-minute preparation budget. Install OS packages in setup. Install shared executable tools under $ZEROSHOT_TOOLS/bin, which is on the PATH of every hook and agent, and project dependencies in the workspace. Shell exports affect only that hook; use variables for later commands. The platform's harness Node interpreter remains separate from a project-installed Node version. Setup, startup, and agent sessions have separate home directories; use $ZEROSHOT_TOOLS for tools shared across them.

Workers and reviewers share files, ignored dependencies, generated output, and services. Startup can start a background service; its process belongs to the run and survives individual agent executions. Wait for required services to be ready before startup exits; the runtime does not infer their health. Setup is for installation: start services from startup. Do not daemonize processes or start root services in setup. Setup cancellation cleans up its shell process group; a root script can escape that group, so this is not containment for untrusted root code. The target images suppress Debian package service autostart. Parallel graph branches share mutable state, so scripts and graphs must coordinate concurrent writes.

Both hooks run again on resume: setup, restore workspace files, startup, then restart or continue the graph. Startup must be idempotent with respect to existing workspace files. Checkpoints restore supported node-instance agent conversations on checkpoint continuations and suspended successors. Running services, Docker images or volumes, and database transactions are not restored. A background process may change files while a checkpoint is captured; use application-managed exports for consistent database recovery.

A direct Docker target is an operator-trusted container. Root setup changes that container's OS, including for other runs it hosts. Use separate disposable target containers for independent OS requirements. The target must have a writable root for package installation. Docker commands need an operator-provided daemon endpoint. Detached Docker containers belong to that daemon and are not terminated by the target's process cleanup. Direct target operators or scripts must manage their names, reuse, and removal. When the daemon runs inside a disposable run machine, destroying that machine removes its Docker resources. Local execution uses the invoking machine and rejects setup and startup hooks and their connection references.