Environments
Prepare dependencies and network access for a run, independently of its profile.
Create an environment
Open Environments and choose New environment. Name it and choose Personal or Org: Personal environments belong to you; owners and admins manage shared Org environments. Create opens its page, where you set the parts below and choose Save changes. 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. |
{
"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 under Preparation connections choose Add connection and enter that name and field. Each row shows whether runs you start get your personal connection or the org's. 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
Under Network, choose a mode for Internet access.
None | Only the extra hosts. An empty list blocks public egress. |
|---|---|
Baseline | The shared hosts listed on the environment's page, plus the extra hosts. |
All | Any reachable host through the Platform proxy. New environments use this mode. |
Under Extra hosts, 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.
Under Private HTTPS origins, an org admin can select approved services from the org’s private networks. Each selection routes that exact HTTPS origin through the chosen network in every internet access mode. A run needs an explicit route for any origin registered as private by its org, even under All. Personal environments cannot select private routes.
Hosted runs use the Platform proxy for internet traffic in every mode. In None and Baseline, clients need to trust the installed CA and host Docker access is blocked. Docker builds and sibling containers require All. DNS, local services, and trusted Platform endpoints remain reachable. See credential destination rules and the Tailscale gateway guide.
Assign repositories and run
Each environment lists the repositories that use it. On its page, under Repositories → Choose repositories, pick from the repositories available through your personal GitHub connection or the Org GitHub App, apply the selection, then choose Save changes. Repositories assigned to another environment show that environment's name and can't be chosen; remove one from its environment before assigning it elsewhere. Future repositories are not added automatically.
On Start a run, the environment assigned to the repository is picked automatically. Choose a different Personal or Org environment, or No environment setup, to override it for that run only. Unassigned repositories run without environment setup. When a Personal and an Org environment are both assigned, neither wins: choose one for the run. Organization automation uses only Org assignments.
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.