Configuring Agent Sandboxes for Monorepo Codebases
Scope each agent to one package, its dependencies, and its credentials.

Configuring agent sandboxes for monorepo codebases means bounding context, execution, network access, and credentials around the task. With these boundaries, an agent can produce a usable pull request without spending its run exploring irrelevant code and acting beyond its remit. The central configuration decision is to make the package and its verified dependencies the working unit.
Why monorepos break the assumptions agent sandboxes are built on
An agent looks through a 50-package root before it touches a single file. Infrastructure configs, generated artifacts, unrelated services, and sibling packages are all accessible, but accessibility says nothing about relevance. The sandbox has exposed the repository without explaining its structure. Before the agent can work, it must find out which parts it needs.
Most agent sandbox defaults assume one runtime, one dependency tree, one set of credentials, and one entry point. A monorepo breaks those assumptions simultaneously, so mounting the root does more than increase the amount of source available. It exposes multiple execution environments and potentially the credentials for every service the repository touches. Meanwhile, the agent cannot see dependency ordering, affected-package detection, and workspace filtering unless it has the tools or context to use them. The result can be prolonged exploration, an exhausted context budget, or changes whose blast radius extends beyond the intended package.
How context overflow becomes the dominant failure mode at monorepo scale
The agent opens a file, follows its references, and moves from one package to another through dependency chains. Each read consumes context that the task will later need for reasoning and output. A monorepo with hundreds of thousands of lines of code can therefore exceed even a large context window before the agent begins its actual work.
Source volume and the absence of a relevance boundary both contribute to context overflow. Agents do not skim a codebase as humans do, and broad exploration does not reliably distinguish architectural dependencies from incidental detail. Anthropic's large-codebase guidance identifies a giant root CLAUDE.md and stray file reads as primary causes of context window degradation. In parallel workflows, each broadly exploring agent repeats that waste, multiplying the cost across concurrent runs. With a larger context window, the agent still reads files it does not need, but filesystem scoping keeps those files out of the window from the start.
Scoping the filesystem: how to bound what the agent can see before it starts
Start the agent in the narrowest directory that contains everything the task legitimately needs. In Claude Code, cd packages/api && claude roots its working context at the package. It reads that package's CLAUDE.md and every ancestor CLAUDE.md, including the root file, with the subtree and local dependencies providing the task's source context. In Cursor, add only the package directory to the workspace. For a cross-package task, add exactly the packages involved.
Explicit exclusions strengthen that initial boundary. A .claudeignore file can exclude generated artifacts, unrelated sibling packages, infrastructure folders, and build caches. Common targets include **/dist/, **/.nx/, **/node_modules/, and **/*.generated.ts. Anthropic also recommends Read deny rules to limit stray file reads, so directory selection should not be treated as a substitute for access controls. For parallel work, give each agent a separate git worktree and branch so its edits remain in its own checkout. That separates in-progress changes, while execution isolation remains a separate requirement.
Giving agents a readable map instead of raw source: per-package CLAUDE.md and AGENTS.md
Once irrelevant files are excluded, the agent needs a concise account of the structure that remains. The root CLAUDE.md should explain how the monorepo is laid out, where the shared tooling is, and which rules apply across packages, then point to package-level instructions. A rule such as “never import across package boundaries directly” belongs at that shared level. The root file is a navigation document. Keeping the root file in that role stops the shared context from using up the budget that scoping was meant to protect.
Each package-level CLAUDE.md should instead act as a working specification. It should name runtime and framework versions, entry points, service dependencies, test commands, and generated directories that must not change. A package might specify Node.js 22, Express 5, PostgreSQL 16, and Drizzle ORM, with src/server.ts and src/routes/ as entry points and src/generated/ excluded from edits. AGENTS.md supports the same root-map and package-contract pattern for harnesses that use that convention. In Turborepo repositories, task descriptions in turbo.json can explain intent, but the context file should also explain that dependsOn controls ordering and a ^ prefix means “build my dependencies first,” applying the task to dependencies outside the same package.
Isolating the execution environment: microVMs and per-task sandboxes
A readable, bounded workspace does not prevent a command from affecting the host. Package installation, migrations, and container operations require an execution boundary as well. Each agent run should have its own kernel, Docker daemon, and network stack so the side effects of one run cannot reach the environment of another. Containers share the host kernel, whereas a microVM supplies a separate kernel for the agent's processes, packages, and filesystem.
Docker Sandboxes implements this pattern with a dedicated microVM, a private Docker daemon, and a proxy that filters outbound traffic. The workspace is shared read-write with the host by design, but host processes and the host Docker engine are outside the VM. Agents can build and run containers without privileged mode or a mounted host Docker socket. Combined with a per-worktree checkout, this separates parallel agents' execution and changes.
For macOS local development, Sandvault offers a different boundary through a sandboxed non-admin user. Install it with brew install sandvault, then launch an agent with sv codex or sv claude, or open a shell with sv shell. Both users can use repositories under /Users/Shared without copying them, but the sandbox user cannot get to the primary user's tokens or sensitive files. This is a local-development pattern, with production-scale use still requiring per-task microVM isolation.
Network policy configuration inside a monorepo sandbox
Even with execution isolation, each task needs rules for which endpoints the agent may reach. A package may need internal npm or PyPI mirrors, external registries, CI/CD APIs, the version control host, or integration-test services. Another package may need a different set. Blocking everything prevents legitimate work, but allowing everything discards the boundary established elsewhere.
Docker Sandboxes provides three network tiers, namely Open, Balanced, and Locked Down. Open allows all traffic, while Balanced uses default deny with common development sites allowed. Balanced is the starting point for most monorepo tasks because it blocks internal network resources and the host's localhost while allowing package registries, version control hosts, AI provider APIs, container registries, and common cloud services. Build any additional allowlist from the endpoints required by the specific package and task.
For sensitive services, use Locked Down and name the endpoints to allow through sbx policy allow or a kit rule. A migration task that uses a production-adjacent database should not also let the agent reach any external site it chooses. Docker Sandboxes' proxy can inject authentication headers without placing the credentials inside the sandbox. That separates permission to reach a destination from possession of the token used there.
Credential scoping across a monorepo's services
Network policy limits where an agent can call, but credential scope determines what it can authenticate as. Repo-level environments and CI configuration can expose version control tokens, cloud keys, registry tokens, database URLs, and third-party API keys. Giving all of those credentials to an agent for a package task lets it do things outside its work. The credential boundary must therefore follow the task.
Mint a throwaway token for the single repository and permissions required, set a short expiry, and revoke it when the session ends. For most coding tasks, a GitHub token with read-only contents and write-only pull-requests is sufficient. The agent does not need org-level read or package write unless the task requires it. Long-lived cloud credentials, including broad IAM roles and service account keys, must stay out of agent sessions.
Where proxy-side authentication is available, keep the token on the host side and let the proxy inject headers. The agent can then make authenticated calls without holding the credential itself. In parallel workflows, issue a separate scoped token to each agent so a leak from one session does not expose a shared credential. Plan expiry and revocation when setting up the task, before an incident forces rotation.
Using Turborepo's and Nx's task graphs to give agents verified scope
With access bounded, the agent still needs to determine which packages its change affects. Turborepo and Nx already encode relationships that would otherwise require broad source exploration. Export Nx's dependency graph with npx nx graph --file=project-graph.json and point to that file in the agent's context. The resulting map gives the agent package relationships without requiring it to read every consumer of a shared utility.
After a change, npx nx affected --target=test runs tests for affected projects. In Turborepo, npx turbo run test --filter=...[HEAD^1] selects changed packages and their dependents for testing. These commands make the graph the basis of verification rather than leaving the agent to guess the change's reach. Turborepo's turbo prune and --filter also help bound build and test work instead of running the full pipeline on every iteration.
Include graph and filter tooling in the sandbox's allowed commands. Then require the agent to use that tooling before and after changes in the task instructions. Affected-only tests provide a focused feedback loop and reduce the chance that unrelated failures derail the task.
Choosing and configuring the agent harness for monorepo work
The choice of harness should meet these configuration requirements as well as take benchmark scores into account. Claude Code's per-directory CLAUDE.md support and 33 hook events provide controls for package context and workflow enforcement. Hooks can enforce scoping rules, validate credentials, and trigger affected-package checks. These controls keep the boundary in place throughout a run, beyond the instructions given at the start.
Codex's sandboxed execution model and CLI-first design fit worktree-based parallel workflows, though usage limits can interrupt long-running monorepo tasks. Cursor's parallel agents can run simultaneously on separate worktrees, supporting concurrent changes across packages. OpenCode's headless server mode and local model options make it a candidate for self-hosted configurations that keep code off external infrastructure.
A mixed-runtime repository may contain Python services, TypeScript apps, and Rust tooling with different harness needs. Staying harness-agnostic lets teams select by package without accepting one tool's limitations everywhere.
A configuration sequence for teams starting agent work on an existing monorepo
Begin by auditing a representative task before changing the configuration. Observe which files the agent reads before writing anything, and use those reads to establish baseline context consumption and identify expensive detours. Next, add ignore rules for generated artifacts and unrelated packages, then write a minimal CLAUDE.md or AGENTS.md for the first target package. Make the root context file a navigation map before adding more packages.
Move execution into a microVM sandbox or sandboxed user before tasks install packages, use credentials, or call external services. Then configure the first task's network policy and mint a short-lived, single-repo token for version control access. Keep long-lived cloud credentials out, and check whether each extra credential is needed for the task and the destinations it is allowed to reach. Wire affected-package verification into the task definition after each change so completion includes a required check.
Start parallel agents in separate worktrees only after those controls work reliably. Each concurrent agent multiplies the cost of a missing exclusion or an overly broad credential. As work expands, measure cycle time from issue to merged PR per package, change-failure rate by harness, and review load on senior engineers. Track each run's cost by harness and model in place of counting lines of AI-generated code. Those measures make sandbox configuration an ongoing discipline tied to usable changes.


