How to use the Sandboxed Coding Agent skill (coding-agent)

What does the coding-agent skill make the agent do?

The skill sets up a smolvm machine that holds a coding agent and mounts your project directory inside it. The agent can then run with full permissions and install anything it needs inside the machine. According to the skill, edits to files appear in your project on the host, and git works on the mounted repo.

The machine is the boundary. Because the agent works inside it, the agent does not need to ask before each command, and installs and experiments stay inside the machine rather than on your host.

• Works with Claude Code, OpenCode, Codex or any other coding agent you list in the install step.
• Keeps the agent's installed tools in a persistent machine, so later starts are quick.
• Project files are mounted from the host, so changes show up in your repo.

How do you install the coding-agent skill?

Download the ZIP from this page and unzip it. Put the resulting folder in ~/.claude/skills/ to make it available across your projects, or in a project's .claude/skills/ folder to make it available only there.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/
• Claude apps: Settings → Capabilities → Skills

What do you need before you start?

The skill needs smolvm installed on your host. It was tested on smolvm v1.27.4 and v1.29.0. You also need an Anthropic API key or another agent API key on the host, and Node/npm inside the machine to install the agents, which the Smolfile's init step handles.

The Smolfile forwards your SSH agent, so SSH_AUTH_SOCK must be set on the host unless you remove the [auth] block.

• smolvm (tested on v1.27.4 and v1.29.0)
• An Anthropic API key or other agent API key on the host
• SSH_AUTH_SOCK set on the host, or the [auth] block removed
• Node/npm inside the machine, via the Smolfile init step

How do you set up the machine and run the agent?

First, copy the Smolfile into your project and edit the npm install line in init to list the agents you use. Then create and start the machine, passing your API key as a reference so it is read from the host at launch and not written to the machine record. The first start runs init, which the skill describes as under a minute once the image is pulled.

Start the agent with machine exec. For anything else, machine shell gives you a shell in /workspace.

• Run machine exec --name agent -- git status to check git. It should print the repo status, not 'dubious ownership'.
• Stop with machine stop --name agent to keep the installed agents; the next start takes about a second.
• Remove with machine delete --name agent -f; your project stays on the host.

How do you trigger the skill with natural requests?

You do not need special syntax. Describe what you want in plain language. The skill's description says to use it when someone wants to sandbox their coding agent, run it in skip-permissions or YOLO mode safely, or give it a disposable environment it can install anything into.

Good requests name the goal and the agent. Examples that match the skill's stated use cases are below.

• "Set up a sandbox so I can run Claude Code in skip-permissions mode."
• "Run OpenCode inside a machine with my project mounted."
• "I want a disposable environment where the agent can install packages safely."

What are the safety notes?

The skill runs scripts and uses the network. The agent inside the machine has network access so it can install and download. To keep the agent off your local network and the host's ports, you can add block_private = true under [network] (from v1.28.1).

The project directory is mounted read-write from the host, so agent edits land in your files directly. The sandbox does not protect project files. It is also not meant for running untrusted code with no network; the skill says to use throwaway-machine for that.

• Project files are mounted read-write; the sandbox does not protect them.
• Set block_private = true under [network] to restrict private network access.
• init runs once, so changing it later needs a new machine or running the new commands with exec.
• For Docker inside the machine, see docker-in-machine.

What tips help the setup go smoothly?

Keep your agent list in the init step accurate, since init only runs on first start. Commit or back up your repo before letting an agent make large changes, because edits go straight to your files.

• If git reports 'dubious ownership', check that the safe.directory line in init ran.
• If start stops with 'ssh-agent: SSH_AUTH_SOCK is not set', run eval $(ssh-agent) or remove the [auth] block.
• Use machine stop rather than delete when you want to keep installed agents.