Run Claude Code or Managed Agents in an Isolated Sandbox

Run Claude Code-style or managed coding agents in a sandbox by giving each agent a scoped workspace, explicit file permissions, controlled shell execution, a network and package policy, clear secrets boundaries, durable logs, captured artifacts, and human review before changes are merged or shipped. The agent can still read code, edit files, install dependencies, run tests, and produce a patch, but the environment around it decides what it can touch, what it can fetch, what credentials it can see, and when a person must approve the next step.

What needs to be isolated

A coding agent is not just a chatbot attached to a repository. Once it can edit files and run commands, it starts to look like a junior build worker with language-model reasoning in the loop. That worker may run npm test, inspect generated files, start a dev server, or try a package install because an error message suggests it. If the workspace is your laptop, a shared CI runner, or a long-lived production-like VM, the blast radius is too broad.

The isolation target is the whole agent work loop:

• The repository checkout and branch the agent can read or modify.
• The filesystem paths the agent can write.
• The commands it can run automatically.
• The commands that require approval.
• The package registries, domains, and APIs it can reach.
• The credentials exposed to the session.
• The logs, diffs, test output, screenshots, and artifacts preserved for review.
• The cleanup behavior after success, failure, or timeout.

Claude Code and other managed coding-agent products may include their own permission systems. Anthropic’s Claude Code documentation, for example, describes permission settings for allowed and denied tools, approval behavior, and sandboxing guidance for local use. Treat those controls as one layer, not the entire boundary. A stronger design puts the agent inside an isolated runtime as well, then applies tool permissions inside that runtime.

Reference architecture

A practical sandboxed agent workflow has four layers:

Layer	Purpose	Typical control
Agent controller	Decides the task plan and tool calls	Model/tool permissions, approval mode, task prompt
Sandbox runtime	Hosts the workspace where commands run	Isolated filesystem, process limits, lifecycle controls
Policy gateway	Decides what actions are allowed	Command rules, network egress rules, package policy, secrets scope
Review surface	Lets humans inspect results	Diff, logs, test results, artifacts, pull request

Keep these layers separate. If the agent controller is compromised by prompt injection, the sandbox runtime and policy gateway should still limit what happens. If a package install pulls unexpected code, the network and artifact logs should make that visible. If the agent produces a plausible patch, the review surface should still show exactly what changed and which tests ran.

A conceptual policy object might look like this:

workspace:
  mode: ephemeral
  repo_ref: pull-request-branch
  writable_paths:
    - /workspace/project
  readonly_paths:
    - /workspace/reference
commands:
  auto_allow:
    - git status
    - npm test
    - npm run lint
    - pytest
  require_approval:
    - npm install
    - pip install
    - docker build
    - git push
  deny:
    - rm -rf /
    - curl ... | sh
network:
  default: deny
  allow:
    - registry.npmjs.org
    - pypi.org
    - files.pythonhosted.org
secrets:
  expose:
    - READ_ONLY_PACKAGE_TOKEN
  deny:
    - PRODUCTION_DATABASE_URL
    - CLOUD_ADMIN_TOKEN
artifacts:
  capture:
    - git diff
    - test-results/
    - screenshots/
    - command-log.jsonl

This is intentionally not an SDK example. The exact policy format depends on your agent framework and sandbox provider. The important point is that permissions should be expressed outside the model’s free-form reasoning, then enforced by the runtime or orchestration layer.

Workspace and repo setup

Start every agent run from a clean workspace. A managed agent should not inherit a developer’s shell history, SSH agent, dotfiles, cloud CLI login, or untracked local files unless there is a deliberate reason.

For repository work, use a dedicated checkout:

• Clone or mount only the repository needed for the task.
• Check out a new task branch instead of editing the default branch.
• Pin the base commit so the review can reproduce the starting point.
• Keep dependency caches separate from writable source paths.
• Store generated artifacts outside the source tree unless they are part of the intended diff.

Branch isolation matters because coding agents often try several approaches before settling on one. A clean task branch gives reviewers a normal pull request diff instead of a mixed workspace containing temporary experiments. If the agent needs to compare against a reference implementation, mount that reference read-only.

For long-running managed agents, decide whether the sandbox is ephemeral, paused, or snapshotted. Ephemeral workspaces are easier to reason about. Snapshots and pause/resume are useful for long jobs, browser sessions, and expensive setup steps, but they should still preserve a clear audit trail: when the snapshot was created, which files were present, and which credentials were available.

Filesystem permissions

Filesystem scope should be narrower than “the agent can read the whole machine.” Most coding tasks need:

• Read/write access to the repository workspace.
• Read-only access to selected task context, fixtures, or documentation.
• A temporary directory for build output and scratch files.
• No access to host home directories, unrelated repositories, cloud credentials, browser profiles, or production data dumps.

Write permissions deserve special care. A coding agent that can edit a repo can also edit scripts, tests, lockfiles, CI config, and deployment files. That may be exactly what the task requires, but it should be visible in review. For sensitive paths, such as .github/workflows/, deployment manifests, or package publishing config, require either a stronger approval step or a human-owned final review.

Use file allowlists when the task is narrow. For example, a documentation agent may only need docs/ and a generated preview directory. A dependency upgrade agent may need package.json, lockfiles, and test snapshots. A broad refactor needs wider access, but the review should then expect a larger diff and more complete tests.

Shell execution policy

Shell access is where coding agents become useful and risky. They need command execution to run tests, format code, inspect build errors, and verify fixes. They do not need unrestricted authority to run every command without a pause.

A good shell policy has three buckets:

Bucket	Examples	Why it matters
Auto-allowed	git status, npm test, pytest, go test ./..., npm run lint	Keeps normal edit-test loops fast
Approval-required	package installs, migrations, long-running services, external CLIs, git push	Adds friction where state, cost, or network risk changes
Denied	destructive host commands, credential dumping, unsafe shell piping, writes outside workspace	Blocks actions that should not be delegated

Do not rely only on command text matching. Agents can run commands through scripts, package manager hooks, or nested shells. For higher-risk environments, combine command policy with runtime-level filesystem boundaries, resource limits, and network controls.

Long-running commands need timeout behavior. A test server, browser automation run, or build watcher can stay alive after the agent has moved on. Capture process IDs, stdout, stderr, exit status, runtime, and termination reason. If a command opens a preview port, record the port mapping and shut it down during cleanup.

Package installs and network egress

Package installation is one of the most useful features of an agent workspace and one of the easiest places for risk to enter. A coding agent may install a package because a Stack Overflow answer, README, or model-generated plan suggested it. That can change the dependency graph, execute install scripts, and reach external registries.

For implementation guides and production workflows, start with a default-deny network posture, then allow what the task needs:

• Package registries such as npm or PyPI, preferably through a registry mirror or cache.
• Source hosts needed for the repository and submodules.
• Documentation domains needed for the task.
• Internal APIs only when the sandbox has the right data classification.

Avoid giving every agent broad outbound internet by default. If broad access is required for research or browser automation, separate that run from code-modifying runs and label the artifact accordingly.

For package installs, record:

• The package manager command.
• The registry host.
• Lockfile changes.
• Downloaded package names and versions when available.
• Any install scripts that ran.
• Whether a human approved the install.

This does not make arbitrary packages safe. It makes the change reviewable.

Secrets boundaries

Secrets should be scoped to the task, short-lived, and absent by default. The safest sandbox is not one that promises a model will never reveal a secret; it is one where the secret is not present unless the task truly requires it.

Use these defaults:

• No production database credentials in agent workspaces.
• No cloud admin tokens.
• No personal SSH keys or developer machine credentials.
• Read-only credentials where possible.
• Separate tokens for package reads, test fixtures, or staging-only APIs.
• Redaction in logs before artifacts are shared.

If the agent must call an external service, provide a narrow token and record which tool or command used it. Avoid placing broad credentials in files the agent can edit. Environment variables are convenient, but they can still be printed by commands, included in logs, or copied into generated files. Treat them as exposed to the agent process.

Logs, artifacts, and audit trails

Human review is only useful when reviewers can see what happened. A sandboxed coding-agent run should preserve more than the final patch.

Capture at least:

• The task prompt or instruction summary.
• The base commit and branch.
• Files read and written when your tooling can record them.
• Commands run, with timestamps, working directory, exit status, stdout, and stderr.
• Package installation and network access summaries.
• Test and build results.
• Generated files, screenshots, reports, or preview links.
• The final diff.

Store logs in a review surface that outlives the sandbox. If the sandbox is destroyed immediately after the run, the evidence should still be available in the pull request, CI artifact store, or agent platform record.

For teams using managed agents, this audit trail also helps compare agent performance. You can see whether failures came from missing dependencies, a denied command, an unclear prompt, flaky tests, or a real code issue.

Cleanup and reset

Sandbox cleanup is a security and cost control, not just housekeeping. At the end of a run:

• Stop background processes.
• Close exposed ports.
• Revoke task-scoped tokens.
• Export required artifacts.
• Delete temporary files that are not part of the review.
• Destroy, pause, or snapshot the sandbox according to the run type.

Ephemeral reset is the cleanest default for untrusted or exploratory work. For long-running agents, snapshot only after a known-good setup step, not after arbitrary agent activity. If a failed run needs investigation, preserve the sandbox or snapshot with a clear expiration time.

Where Novita Agent Sandbox fits

Novita Agent Sandbox is designed for AI-agent execution workflows where code runs inside isolated cloud workspaces rather than on a developer laptop or shared host. Novita’s Sandbox documentation describes core primitives that map to the pattern in this guide: sandbox lifecycle management, filesystem operations, command execution, templates, and runtime management for agent workloads.

That makes Novita a fit for teams building coding-agent, data-analysis, browser-agent, evaluation, or long-running agent workflows that need an execution environment alongside model APIs. Keep the boundary clear, though: this article is a general implementation pattern for Claude Code-style and managed coding agents. It is not claiming an official Claude Code integration, a partnership, or universal compatibility with every managed-agent product.

If you are designing a Novita-based workflow, use the product docs for the exact released API surface and keep your policy layer explicit. The sandbox can provide the isolated execution workspace; your application should still decide command approvals, network policy, secrets scope, artifact retention, and human review gates.

Security review checklist

Use this checklist before allowing a coding agent to run beyond a toy repository:

Question	What to look for
What is the isolation boundary?	Dedicated workspace, process limits, filesystem separation, and clear provider documentation
What can the agent read?	Repo-only access by default, no host home directory, no unrelated repos
What can the agent write?	Writable source paths are explicit; sensitive config paths get extra review
What commands run automatically?	Test and formatting commands are allowed; state-changing commands require approval
What network access exists?	Default-deny or scoped egress; package registries and docs domains are intentional
How are package installs handled?	Lockfile changes, registry hosts, and install scripts are logged
Which secrets are present?	Task-scoped, short-lived, least-privilege credentials only
What happens to logs?	Commands, outputs, diffs, and artifacts survive sandbox cleanup
How is cleanup enforced?	Background processes, ports, tokens, and temporary files are closed or revoked
Who approves merge or shipment?	A human reviewer checks code, tests, security-sensitive files, and generated artifacts

The most important rule is simple: do not confuse “the agent asked for permission” with “the system enforced a boundary.” The model can help explain what it wants to do. The runtime and policy layer should decide what it is allowed to do.

FAQ

Can you run Claude Code in a sandbox?

Yes, if your setup places the Claude Code-style agent inside a scoped workspace and enforces filesystem, shell, network, secrets, logging, and review policies around it. Do not assume that a local permission prompt alone is enough for production or sensitive repositories.

Is a container enough for coding-agent isolation?

Sometimes, but the answer depends on your threat model. Containers can be useful for repeatable builds and dependency separation, but security-sensitive workloads should evaluate the kernel boundary, host mounts, network defaults, runtime privileges, and provider documentation before treating a container as the full sandbox boundary.

Should agents be allowed to install packages?

They can be, but package installs should be treated as controlled supply-chain events. Prefer registry allowlists or mirrors, lockfile review, install-script logging, and approval for new dependencies or commands that fetch and execute remote code.

What should a human reviewer check before merge?

Review the final diff, commands run, tests executed, package and lockfile changes, touched CI/deployment files, generated artifacts, and any denied or approval-required actions. For security-sensitive repositories, review the sandbox policy itself as part of the change.

Does Novita Agent Sandbox officially integrate with Claude Code?

This article does not make that claim. Novita Agent Sandbox provides isolated execution primitives for agent workflows, while Claude Code and managed-agent products have their own product-specific interfaces and permission models. Validate the exact integration path against current product docs before publishing runnable commands.

Recommended articles

• Building a Coding Agent with Novita’s Agent Sandbox
• Run Harbor Agent Evaluations on Novita Agent Sandbox
• How to Use Codex with Novita AI Models