Skip to content
Engineering Standards

Development environment

A clean clone can reach a verified development environment without undocumented workstation state.

Updated View as MarkdownView on Github

A coding agent may run on a maintainer’s workstation or in a clean sandbox. When it runs locally, it may inherit:

  • global packages;
  • shell aliases;
  • running services;
  • credentials;
  • untracked configuration.

That state does not follow the repository to another workstation or sandbox. A covered repository must reach a verified development environment from a clean clone, with every dependency outside the repository declared. Agent instructions owns the exact setup commands. This page sets the bar those commands must meet.

Resolve tools from checked-in files

The repository checks in enough configuration to resolve the tools and dependencies used to build and test it:

  • language runtimes;
  • package managers;
  • system packages;
  • application dependencies and their lockfiles.

Team standards chooses the supported tools and version ranges. The repository resolves an exact working toolchain inside those ranges. A language name or a version written only in the README is not a pin.

The repository chooses the mechanism. For example, the engineering-standards repository uses devenv. Other repositories may use a devcontainer or checked-in runtime version files. Name any prerequisite that remains outside the repository, state its supported version, and link to its installation instructions.

Give the agent a short toolchain map:

AGENTS.mdmarkdown
## Setup

Toolchain:

- Node.js: resolved by `.tool-versions`
- pnpm: resolved by the `packageManager` field in `package.json`
- System packages: resolved by `.devcontainer/devcontainer.json`

Install locked dependencies with `pnpm install --frozen-lockfile`.

Separate human bootstrap from repository setup

Some prerequisites belong to a person or a managed workstation. Examples include:

  • signing in to GCP;
  • granting access to a private package registry;
  • installing a company certificate.

Put these steps in the root AGENTS.md under Setup, before the commands the agent can run. State which step needs a human and what proves it is complete. Do not hide an authentication prompt halfway through setup.

After bootstrap is complete, repository setup runs from the repository root without prompts or a graphical interface. It installs the versions resolved by checked-in configuration and leaves lockfiles unchanged.

AGENTS.mdmarkdown
## Setup

Human bootstrap:

1. Sign in with `gcloud auth application-default login`.
   Completion check: `gcloud auth application-default print-access-token` succeeds.
2. Request access to the private package registry through the owning team.
   Completion check: `npm whoami --registry <registry-url>` prints your username.

Repository setup:

1. Run `./scripts/agent-setup.sh` from the repository root.
2. Run `./scripts/verify-setup.sh`.

Prove setup from a clean clone

Every covered repository has a clone-to-verified path. Run it in an empty, disposable environment, such as:

  • a Docker Sandbox in clone mode;
  • a newly built devcontainer;
  • a temporary virtual machine;
  • a clean CI runner.

A successful run on a maintainer’s workstation does not prove that the repository contains everything setup needs.

The path ends with the setup verification required by Agent instructions. The result depends on what the repository produces:

  • an application starts and reports ready;
  • a library builds and runs a focused test;
  • an infrastructure repository initializes without a remote backend, validates, and renders or plans without applying.

The required path must be enough to validate a normal small change. It does not need to reproduce the whole production topology on a laptop.

AGENTS.mdmarkdown
Clean-clone verification:

1. Run `./scripts/agent-setup.sh`.
2. Run `./scripts/verify-setup.sh`.
3. Expect the command to exit zero and print `environment ready`.

Do not use files, packages, or services from outside the clone.

Configure coding-agent environments

Keep setup logic in the repository. Provider settings call it; they do not replace it. The setup command must:

  • run from the repository root;
  • finish without prompts;
  • be safe to run more than once;
  • install the locked dependencies;
  • fail when verification fails.

The examples use ./scripts/agent-setup.sh. A repository may use another command, but AGENTS.md and every provider configuration must call the same one. If the repository needs local services, provide a separate ./scripts/agent-start.sh that starts them and reports when they are ready.

Configure each agent according to its execution model:

Commit the SessionStart hook so the same project setup runs in local and cloud sessions. In the environment selector at claude.ai/code, use the setup script only for operating-system tools missing from the supplied image.

The cloud setup script runs as root when Anthropic builds the environment cache. It does not preserve running services. Start services in the session hook or through the exact command in AGENTS.md.

Ordinary environment variables are readable by the session. Use API credentials for secrets and restrict network access to the domains the repository needs.

Put the setup command in the cloud environment’s setup script. Use the maintenance script only to repair a reused environment, and keep both safe to rerun.

Codex has no repository file for cloud environment settings. AGENTS.md must tell it when to run the service-start command. Store nonsecret values in environment settings. Codex exposes secrets only during setup and removes them before the agent phase.

Keep agent internet access off unless the task needs an allowlisted domain and HTTP method.

Commit .cursor/environment.json. Cursor runs install to completion while creating a Build, then saves the disk state. It runs start for every agent.

Keep long-running services out of install, and omit start when the repository needs none. Store secrets and network rules in the Cloud Agents dashboard, not in the repository file.

OpenCode does not provide a hosted repository environment. Its supported remote path runs inside a GitHub Actions runner.

Put setup and service startup in ordinary workflow steps before the OpenCode action. The workflow owns the runner image, tool versions, cache, secrets, permissions, and network policy. Pin every action to a full commit SHA before committing the workflow.

Use sandboxed environments with coding agents

Use Docker Sandboxes (sbx) for clean-clone checks when the tool is available and approved. It runs the coding agent in a microVM with its own filesystem, Docker daemon, and network.

Use clone mode for this check. The agent works in a private clone inside the sandbox, while the host repository is mounted read-only. Docker Sandboxes supports every approved agent:

Run the repository’s setup and verification commands inside the sandbox. A missing package, service, variable, or network rule then fails in a place that does not inherit the maintainer’s setup.

Sandboxes keep installed packages and configuration when stopped. Remove and recreate the sandbox before a clean-clone check. Use sbx policy for the declared network endpoints, sbx ports for local services, and sbx secret for supported credentials.

Use worktrees for concurrent local work

Give each local agent or task its own Git worktree and branch. A worktree has a separate working directory and Git index, so one agent cannot overwrite another agent’s uncommitted files or staged changes. Worktrees also let a maintainer review one task while another agent continues elsewhere.

Worktrees do not isolate processes, ports, containers, databases, or caches outside the repository. Assign unique ports and Compose project names when two worktrees run the application at the same time. Use a Docker Sandbox when the task needs operating-system, process, or network isolation.

Create and remove an agent worktreebash
git fetch origin
git worktree add ../repository-nt-12345 -b agent/nt-12345 origin/main
cd ../repository-nt-12345

# Run the agent from this directory. Before cleanup, commit or move its work.
git status --short
cd ../repository
git worktree remove ../repository-nt-12345
git branch -d agent/nt-12345

Record the worktree rule in the root instructions:

AGENTS.mdmarkdown
Concurrent work:

- Use one branch and worktree per task.
- Run the coding agent from that worktree.
- Use unique ports and local service names.
- Do not remove a worktree until `git status --short` is empty.

Declare local and external dependencies

The Setup section of AGENTS.md, or a checked-in document it points to, names everything the clone-to-verified path starts or reaches:

  • local services and their ports;
  • test dependencies and the command that starts them;
  • seed data and the command that creates it;
  • external network endpoints and package registries;
  • required environment variables and where local values come from.

Check in an example environment file when the application needs environment variables that have no checked-in defaults. It lists every required variable. Each value is a safe local default or an empty placeholder. Secret values stay in the approved secret store; the repository records their names only. See Security.

Local data is disposable and does not come from production. Testing owns test isolation and fixtures.

AGENTS.mdmarkdown
Local dependencies:

- PostgreSQL 16 on `127.0.0.1:5432`: start with `docker compose up -d postgres`
- Test data: create with `./scripts/seed-test-data.sh`
- Package registry: `<registry-host>` over HTTPS
- Required variables: copy `.env.example` to `.env.local`

Readiness check: `./scripts/check-local-dependencies.sh`.

Keep basic setup local

The clone-to-verified path may download dependencies and read approved external systems. It does not create, update, or delete shared infrastructure or data.

A workflow that changes an external system is separate from basic setup. Its instructions name:

  • the exact project, cluster, namespace, database, or account it changes;
  • the approval required before it runs;
  • the command that shows what exists;
  • the cleanup command and the state it leaves behind.
AGENTS.mdmarkdown
Basic setup may download locked dependencies and start local containers.

Basic setup must not:

- run `terraform apply`;
- deploy to Kubernetes;
- write to a shared database;
- create cloud resources.

Stop and request approval before running a command that changes an external system.

Reset only disposable state

Provide an exact reset command when local setup creates state that outlives a process. The command:

  • states what it removes;
  • restricts its targets to this repository’s local containers, volumes, caches, and generated configuration;
  • exits with a nonzero status when it cannot prove a target is local and disposable;
  • leaves source files, user files, shared services, and remote environments untouched.

If the repository cannot automate a safe reset, its instructions name the manual recovery and tell the agent where to stop for a maintainer. A broad delete command is not a reset procedure.

AGENTS.mdmarkdown
Reset local state with `./scripts/reset-local.sh`.

The command removes this repository's containers, named volumes, caches, and generated local configuration. It leaves source files, user files, shared services, and remote environments untouched. If it cannot prove a target is local, it exits without deleting it.

References

Navigation

Type to search…

↑↓ navigate↵ selectEsc close