Claude Code sandbox best practices start with one rule: if Claude Code can edit files and run commands without a human approving each step, it should run inside an isolated workspace rather than on a laptop or shared CI runner. That matters even more in headless mode, because the whole point of a headless run is that the agent can keep moving through file edits, shell commands, and dependency installs without waiting for a person to click “allow.” Novita’s Claude Code sandbox guide is the source of truth for the exact template commands and flags. This article focuses on the part teams usually need next: why to sandbox Claude Code in the first place, what can go wrong if you do not, and what production controls to add around the template before wiring it into a real workflow.
Why Claude Code needs a sandbox in headless mode
Claude Code is useful because it does more than draft code. It reads files, edits files, runs shell commands, and iterates after seeing test output. That same capability is why it needs a sandbox when you move from an interactive developer session to unattended automation.
In a local terminal, a human usually catches bad ideas early. You see the repo you opened. You notice when a command reaches for the wrong directory. You can stop an install that looks suspicious. In a headless workflow, those natural checkpoints disappear. The agent only sees the instructions and the environment you gave it.
That is why the right comparison is not “Claude Code vs. no Claude Code.” It is “Claude Code on a real machine” vs. “Claude Code inside an isolated execution boundary.” Once the agent can act autonomously, the workspace becomes part of the safety model.
The risk surface is fairly concrete:
| Risk area | What can go wrong without a sandbox | What a sandbox changes |
|---|---|---|
| Repository scope | The agent edits the wrong repo, branch, or untracked local files | Each task gets a scoped checkout, known base commit, and disposable branch |
| Shell execution | Commands run against the host machine or shared runner | Commands stay inside an isolated filesystem and process boundary |
| Dependency installs | npm, pip, or other package installs execute arbitrary scripts on the host | Package installs happen in a disposable environment with policy and logs |
| Secrets | Agent-visible env vars may include broad developer or production credentials | Task-scoped secrets can be limited to the sandbox session |
| Review | The only record is a chat summary or terminal transcript | Diff, logs, stdout, stderr, and artifacts can be captured for review |
If you want a broader sandbox design checklist that is not Claude-specific, read Coding Agent Sandbox: How to Run Agent-Generated Code Safely and Run Claude Code or Managed Agents in an Isolated Sandbox. The difference here is that Claude Code already has a concrete CLI workflow, so the infrastructure question becomes more specific: how do you run that CLI safely when there is no person in the loop?
What changes when you use --dangerously-skip-permissions
This flag is the reason many teams start asking sandbox questions. In normal interactive use, Claude Code can ask before it edits files or runs tools. In unattended automation, approval prompts break the flow, so the Novita docs show the headless pattern with claude --dangerously-skip-permissions -p "<prompt>" inside the claude-code template.
That does not mean the flag is unsafe by definition. It means the safety layer has moved.
When you use --dangerously-skip-permissions, you should assume:
- Claude Code may edit files immediately.
- Claude Code may run commands immediately.
- Claude Code may continue through a multi-step task without pausing for review.
The correct response is not to use the flag on a real workstation and hope for the best. The correct response is to use it only inside a sandbox where the workspace, repo, commands, secrets, and network surface are already constrained. The sandbox boundary becomes the place where you reduce blast radius.
That is also why you should keep the wording precise when documenting this setup. --dangerously-skip-permissions is not a recommendation for local-machine convenience. It is a sandbox-only operational pattern for headless automation. If your workflow still points Claude Code at a developer laptop, shared bastion, or production-like runner, you have removed the human approval prompt without adding the infrastructure control that should replace it.
If your team is still deciding whether to trust package installs in that environment, pair this article with How to Safely Allow Package Installs in AI Agent Sandboxes and AI Agent Sandbox Isolation Boundary Checklist.
How Novita’s claude-code template maps to a production workflow
The useful part of the Novita docs is that they do not stay abstract. They show the actual mechanics a production workflow needs.
1. Headless -p and --print mode
The docs use Claude Code in non-interactive -p mode so the run can accept a prompt, print its result, and exit. That matters because headless automation needs a clean programmatic contract. You do not want a long-lived interactive terminal attached to a human session; you want a task-oriented run that can be started, observed, and torn down.
This is the same split discussed in Claude Code CLI Documentation: interactive Claude Code is for a human driver, while -p plus structured output is what makes the CLI useful in scripts and agent pipelines.
2. Custom model routing through ~/.claude/settings.json
The Novita docs also show a practical detail many teams miss: writing ~/.claude/settings.json inside the sandbox so Claude Code receives its API token, base URL, and model configuration through the env block. That pattern matters for two reasons.
First, it keeps the runtime self-contained. The sandbox can boot with the exact Claude-facing configuration the task needs, rather than inheriting whatever is present on a developer’s machine.
Second, it supports explicit environment control. If your workflow uses Claude Code with a custom backend, the sandbox config becomes part of the reviewed setup instead of hidden personal shell state.
3. Real repo cloning with scoped credentials
The docs show sandbox.git.clone(...) with a target path, shallow clone depth, and GitHub token for private repositories. This is not a minor convenience feature. It is the difference between a reproducible task workspace and an agent working in an ambiguous directory.
For production use, the safer pattern is:
- Clone only the repository needed for the task.
- Pin the starting ref or commit when your workflow requires reproducibility.
- Use a task branch for agent changes.
- Pass scoped Git credentials that can read or write only what the task needs.
If a repo does not need write access yet, do not give it write access just because the agent might eventually open a PR.
4. Structured output plus session_id for multi-step work
The docs show a second useful pattern: start Claude Code with --output-format json, parse the returned session_id, then continue with --resume <session_id>. That is what turns a one-shot code edit into a multi-step workflow you can manage programmatically.
This is the right fit for tasks like:
- Step 1: inspect repo and produce a refactoring plan
- Step 2: resume the same session and implement one slice
- Step 3: resume again to run follow-up verification or cleanup
The important best practice is not “always use resume.” It is “resume intentionally.” If your workflow benefits from continuity, resume the same session in the same sandbox. If the task should be independently reviewable, start a fresh sandbox instead of carrying state forward implicitly.
5. Kill the workspace after the task
The Novita docs end the examples by killing the sandbox. That is exactly the habit you want in production. A headless coding agent should not quietly accumulate stale workspaces, background processes, or lingering credentials. A disposable environment is easier to reason about than a mystery machine with history.
If you want the bigger architectural picture around that runtime model, Building a Coding Agent with Novita’s Agent Sandbox is the right companion read.
Claude Code sandbox best practices checklist
The following checklist is the production version of the docs workflow. It keeps the exact Novita template mechanics, then adds the controls an automated pipeline usually needs.
- One sandbox per task: Do not point multiple unrelated tasks at one long-lived Claude Code environment. Fresh workspaces make the starting repo state obvious and teardown easier.
- Scoped Git access: If Claude Code only needs to clone and inspect a repo, use a read-only token. If it must push a branch, use a token scoped to that repo and that workflow. Avoid inherited personal credentials.
- Sandboxed package installs: Claude Code often needs dependencies to reproduce a failing build or test. That is fine, but installs should happen inside the sandbox with logs and policy, not on the operator’s machine. Review lockfile changes like any other code change.
- Treat shell output as evidence: Capture stdout, stderr, exit codes, and the commands that actually ran. A final summary from the agent is useful, but it is not enough for review on its own.
- No default production secrets: Prefer short-lived or staging-only credentials. A coding agent that can read the repo and run commands does not need broad cloud admin tokens or production database credentials by default.
- Review the diff, not just the outcome: Headless success only means Claude Code finished the loop you gave it. It does not mean the change is correct or ready to ship. Review touched files, dependency changes, command output, and any generated artifacts.
- Keep
--dangerously-skip-permissionssandbox-local: This is the most important operational rule in the setup. The flag belongs inside an isolated, disposable workspace. It should not be your shortcut for running unattended Claude Code against a real machine. - Separate execution from release: Claude Code may be allowed to inspect, edit, test, and prepare a patch. That does not mean it should also own merge, publish, or deployment decisions. Keep those actions behind a human or an explicit policy gate.
- Resume intentionally: Use
--resume <session_id>when the task genuinely benefits from continuity. Reset the sandbox when you need a clean test of reproducibility or when one task should not inherit another task’s state. - Compare the full provider surface: If you are choosing where to host this workflow, look beyond whether the environment can launch Claude Code. Compare session lifecycle, repo ergonomics, logs, pause and resume behavior, and operational tradeoffs. For that angle, E2B vs. Daytona: AI Agent Sandbox Comparison and Novita Sandbox: A Cost-Effective Alternative to E2B Pro with Seamless Compatibility are the relevant comparison reads.
Common mistakes to avoid
The most common Claude Code sandbox mistakes are operational, not conceptual.
Mistake 1: Treating the docs example as a full production policy
The docs show how to launch the claude-code template correctly. They do not try to be your complete review, network, or secret-management policy. Use them for syntax and runtime mechanics, then add your own repo and approval boundaries.
Mistake 2: Reusing a developer workstation as the “sandbox”
Running Claude Code from a terminal on your laptop is a valid developer workflow. It is not the same thing as a disposable, isolated runtime for unattended automation.
Mistake 3: Leaving session state implicit
If you use --resume, know what state you are carrying forward and why. If the answer is “we are not sure, but it was convenient,” you are creating a harder review problem.
Mistake 4: Mixing real secrets with exploratory code work
A sandbox is there to reduce blast radius. If the workspace can still reach production systems with broad credentials, you have weakened the most important boundary.
Mistake 5: Trusting a successful run more than the evidence
An agent can finish a task and still make the wrong change, touch the wrong files, or add a dependency you did not want. Review the diff and logs, not only the narrative summary.
FAQ
Does --dangerously-skip-permissions mean Claude Code has no safety at all?
It means Claude Code is no longer waiting for interactive approvals inside the session. The intended safety layer in a headless workflow is the sandbox boundary around the session: isolated repo, limited credentials, command execution inside the sandbox, captured logs, and human review before merge.
Should every Claude Code automation run in a fresh sandbox?
Fresh sandboxes are the cleanest default for independent tasks. Resume-based workflows are useful when the same multi-step task needs continuity, but the state should be deliberate and reviewable, not accidental.
Can Claude Code install packages safely in a sandbox?
It can be made safer, but not automatically safe. Use package policy, lockfile review, scoped network access, and audit logs. Package installs are one of the highest-risk steps in an unattended coding workflow.
Is the Novita docs page enough to implement the workflow?
It is enough for the released template syntax and the supported Claude Code mechanics: headless runs, settings.json configuration, sandbox.git.clone, JSON output, and session resume. For production rollout, you still need your own review, credential, and policy decisions around that runtime.
