Environments

Prepare dependencies and network access for a run, independently of its profile.

Create an environment

Open Environments, choose User or Org, then New environment. User environments belong to you; owners and admins manage shared Org environments. Creating one needs no GitHub connection.

`Setup`	Runs as root before checkout or checkpoint restoration. Install system packages and shared tools.
`Startup`	Runs as the workspace owner inside the repository. Install dependencies and start services.
`Variables`	Public values for scripts and agents. Shell exports in one script do not persist.
`Preparation connections`	Declared secret fields supplied from Connections, independently of agent-node fields.

environment.json

{
  "setup": "apt-get update && apt-get install --yes --no-install-recommends libssl-dev",
  "startup": "npm ci --no-audit --no-fund",
  "variables": { "CI": "true" }
}

For private packages, save a connection such as registry with NPM_TOKEN, then use Add preparation connection to declare that name and field. Configure the package client to use it in startup.

Preinstalled tools on Ubuntu 24.04 include Node/npm, Python, Rust, Git, C/C++ build tools, Chromium, and Playwright CLI. Install shared executables under $ZEROSHOT_TOOLS/bin; setup, startup, and agent sessions have separate homes. Wait for services to be ready before startup exits. For pinned project runtimes, follow the installation examples.

Network access

Choose Allowed hosts before saving:

`None`	Only custom hosts. An empty list blocks public egress.
`Baseline`	The shared hosts visible in the editor, plus your custom hosts.
`All`	Unrestricted public network access.

Enter up to 128 hostnames, one per line, without URLs, ports, or IP addresses. *.example.org covers subdomains; add example.org separately. Include checkout, provider, package download, and redirect hosts.

None and Baseline require proxy-aware clients that trust the installed CA; direct outbound sockets and host Docker access are blocked. Docker builds and sibling containers require All. DNS, local services, and trusted Platform endpoints remain reachable. Credential destination rules apply separately, including in All.

Assign repositories and run

Each environment lists the repositories that use it. Open Environment repositories, choose Manage repositories, apply the selection, then save the environment. Repositories assigned to another environment are unavailable and show that environment's name. Remove a repository from its existing environment before assigning it elsewhere.

Quick Run shows the assigned environment automatically. Select a different User or Org environment, or None, to override it for this run only. Unassigned repositories run without environment setup. Changing repositories clears the previous run's override.

Repository choices come from your User GitHub connection or the Org GitHub App. Search and group selection apply across matching pages; future repositories are not added automatically. Organization automation uses only Org assignments and credentials. Conflicting User and Org assignments require an explicit choice instead of silent precedence.

In the CLI, --environment FILE supplies a per-run definition;--no-environment disables environment setup for that run. Otherwise the repository assignment applies. Other Git remotes accept an explicit saved reference through MCP/API or a concrete definition.

Preparation, edits, and resume

Follow Preparing environment and the run logs. Graph execution starts after both scripts succeed. Each script has fifteen minutes within a thirty-minute preparation budget; failure stops the run without using agent retries.

Accepted and resumed runs keep their environment and host policy. Both scripts run again on resume, so startup must tolerate restored dependencies and files. Checkpoints do not restore services or Docker state. Submit a new run to use edited scripts or host rules.