How do I run Claude Code safely on Linux?

01Steps

1. Install the sandbox's dependencies. Claude Code's Linux sandbox uses bubblewrap for filesystem isolation and socat to relay network traffic through its proxy. sudo apt-get install bubblewrap socatCOPY sudo dnf install bubblewrap socatCOPY
2. Turn the sandbox on and make it fail closed. failIfUnavailable makes Claude Code exit at startup if the sandbox cannot start; allowUnsandboxedCommands set to false stops the retry outside the sandbox. Run /sandbox inside a session to check its state. claude --permission-mode default --settings '{"sandbox": {"enabled": true, "failIfUnavailable": true, "allowUnsandboxedCommands": false}}'COPY
3. Install kosa8 on an x86-64 machine with KVM. The installer puts the daemon in place and says what else to install: cloud-hypervisor, virtiofsd and access to /dev/kvm. kosa8 doctor checks each one and names the fix. curl -fsSL https://kosa8.com/install.sh | shCOPY sudo apt-get install virtiofsdCOPY sudo usermod -aG kvm "$USER"COPY kosa8 doctorCOPY
4. Start the daemon. Log out and back in after joining the kvm group, then start the background service. Nothing runs until it is up. kosa8 daemon startCOPY
5. Run Claude Code inside its own microVM. Set your key in your own shell only, preview the plan, then run the claude kit on one project folder. The sandbox is removed when Claude Code exits; the folder keeps its changes. export ANTHROPIC_API_KEY=sk-ant-...COPY kosa8 agent run --dry-run -w ~/code/api claudeCOPY kosa8 agent run -w ~/code/api claudeCOPY
6. Review what it did and approve held calls. Every brokered request and tool call is in a hash-chained audit log, and risky calls such as a force push wait for a person. kosa8 audit lsCOPY kosa8 mcp asksCOPY kosa8 mcp approve IDCOPY

02What does Claude Code's sandbox use on Linux?

bubblewrap for filesystem isolation and socat to relay network traffic through a local proxy that allows only the domains you list, which start empty. It wraps shell commands only: Claude's Read, Edit and Write tools, WebFetch, hooks and local MCP servers run outside it, and by default commands can still read most of the filesystem, including credential files, unless you deny them.

Use sandbox.filesystem.denyRead for paths such as ~/.ssh and ~/.aws, and permission deny rules such as Read(./.env) for Claude's own file tools. docker does not work inside the sandbox; Anthropic suggests excluding the commands you need with excludedCommands.

03Why is Claude Code's sandbox not working on Linux?

Usually a missing dependency or a blocked user namespace. If bubblewrap or socat is missing, Claude Code runs commands without sandboxing by default; set sandbox.failIfUnavailable to true to make it exit at startup instead. On Ubuntu 24.04 and later, the default AppArmor policy stops bubblewrap creating the user namespaces it needs, and Anthropic's docs give an AppArmor profile that fixes it.

Two more cases from the same page: inside an unprivileged container bubblewrap cannot mount a fresh /proc, and enableWeakerNestedSandbox works around it only when the outer container is already the boundary you rely on; and on WSL1 Claude Code reports that sandboxing requires WSL2.

04How do I run Claude Code in a VM on Linux?

On an x86-64 Linux machine with KVM, kosa8 runs each agent in a microVM with its own kernel, using Cloud Hypervisor. kosa8 agent run claude starts Claude Code in a VM that sees one project folder, reaches only the hosts the kit names, and holds a placeholder instead of your API key; a broker on the host adds the real key to requests bound for api.anthropic.com.

• Every tool, not only Bash. File edits, package installs and any MCP server Claude Code starts are on the far side of the VM boundary too.
• Checked tool calls. With the claude kit, each tool call is checked against kosa8's rules before it runs: a download piped into a shell is refused, and a force push waits for approval.
• Stop everything. kosa8 sandbox pause --all freezes every running sandbox with its memory and files intact.
• The shared folder is still shared. Claude Code can change anything in it, including .git and any .env. Commit first.

05Can a Linux server run the sandboxes for my other machines?

Yes. Machines that cannot run sandboxes themselves, such as an Intel Mac, Windows 10 or Windows on ARM, can drive an x86-64 Linux box. On the Linux machine, start the daemon listening on an address and print a pairing code for the URL the other device will reach it at, usually a TLS tunnel; on the other machine, join with that code, and every kosa8 command then works normally.

Treat the pairing code like a password: anyone holding it can drive that machine.

06Other options

• Claude Code's /sandbox alone fits day-to-day work on your own code, with failIfUnavailable, denyRead and allowedDomains set.
• A dev container or Docker fits teams that already use one; Anthropic documents a dev container with an example egress firewall.
• gVisor runs containers on a kernel implemented in user space, and fits Linux hosts that already run Docker or Kubernetes.
• Firecracker or Kata Containers give KVM microVMs if you are building the tooling around them yourself.
• Docker Sandboxes runs agents in microVMs from Docker's tooling.
• A full VM with libvirt or Lima fits a long-lived, general-purpose guest you manage yourself.
• Hosted sandboxes such as E2B, Daytona or Modal fit agents that should run in the cloud.

Related guides

• How do I run Claude Code safely on a Mac?
• How do I run Claude Code safely on Windows with WSL2?
• Is it safe to use claude --dangerously-skip-permissions?
• How do I stop AI coding agents from reading my .env secrets?
• Docker containers vs microVMs: which isolates an AI agent better?
• How do I run an AI agent sandbox on my own machine instead of the cloud?
• How do I restrict an AI agent's network access to an allow-list?
• How do I undo what an AI coding agent did?