How to Give an AI Agent a Safe, Isolated Environment on Your Own Machine

To give an AI agent a safe place to write and run code on your own machine, run it in a sandbox: a container or microVM with its own filesystem, limited network access and no copy of your real API keys. Hotcell, our open-source sandbox runtime, sets this up in about two commands. Each sandbox gets a short-lived token instead of your key, so a misbehaving agent can't leak anything that works outside your machine.

This guide walks through it step by step. Last reviewed October 2026.

#What "safe" means for an agent

An agent that writes and runs code needs four things kept in check:

• Files. It should only see the project it's working on, not your home folder.
• Network. It should reach the services it needs and nothing else.
• Keys. It should never hold your real API keys, because anything it can read, a prompt injection can make it print or send.
• Resources. It shouldn't be able to use all of your machine's memory or CPU.

Plain Docker covers the first and partly the last. Hotcell adds the other two.

#What you need

• macOS or Linux.
• Node.js 22 or later.
• Docker (Docker Desktop, OrbStack or colima on a Mac). On Linux with KVM, Hotcell can also use Firecracker microVMs. On macOS it can use Apple Virtualization microVMs.

#Step 1: Install Hotcell

npm i -g hotcell
hotcell

The first run is a short guided setup. After that, hotcell shows your sandboxes, with live CPU, memory and cost for each.

If you just want coding agents that run in sandboxes like this, npm install -g directionallylocal sets up Hotcell and Autopilot for you; see the docs.

If you use colima or another Docker runtime on a non-default socket, point Hotcell at it first:

export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock

#Step 2: Add your API key to the host

hotcell keys add openrouter

The key is stored on your machine, outside every sandbox. You can also import a .env file with hotcell keys import .env. It asks, for each variable, whether it should go through the gateway (the sandbox gets a token) or be copied in.

#Step 3: Create a sandbox

hotcell create -n 1 --repo https://github.com/you/app --branch

This creates one sandbox with your repo cloned on its own branch. Use -n 5 to create five, one per agent.

#Step 4: Work inside it

hotcell terminal <id>

This opens a shell inside the sandbox. Run your agent there. Calls to model providers and GitHub go through Hotcell's gateway, which swaps the sandbox's token for your real key on the way out, and meters and caps what each sandbox spends.

For a quick one-off command, create, run and destroy in one step:

hotcell run --setup "pip install ruff" "ruff check ."

#Step 5: Clean up

hotcell rm --all

Every sandbox is gone. Your repo on the host is untouched.

#Plain Docker vs Hotcell

#What it can't protect

The gateway works for credentials sent in an HTTP header, which covers model providers, GitHub and most REST APIs. It can't swap credentials for databases such as Postgres, request-signing schemes such as AWS SigV4, or client certificates. If you copy those into a sandbox, the sandbox can read them.

#Next steps

• To run Autopilot, our coding agent, in five sandboxes at once on one repo, add --autopilot to hotcell create.
• To send tasks from your laptop and get pull requests back, see Directionally Local.
• For how the key swap works, see how to stop a coding agent from leaking API keys.

#FAQs

#Is Docker enough to sandbox an AI agent?

Docker gives the agent its own filesystem, and you can limit its CPU and memory. It doesn't keep your API keys away from the agent or cap what it spends, and outbound network rules are up to you. Hotcell adds those, and can use microVMs for a separate kernel per agent.

#What's the difference between a container and a microVM for agents?

A container shares the host's kernel, so a kernel exploit inside it can reach the host. A microVM, such as Firecracker on Linux or Apple Virtualization on macOS, gives each sandbox its own kernel. Hotcell supports all three.

#Can the agent still call OpenAI, Anthropic or GitHub without the real key?

Yes. The sandbox gets a short-lived token. Hotcell's gateway on the host swaps it for your real key on the way out, and meters and caps what each sandbox spends.

#What secrets can't Hotcell protect?

Credentials that aren't sent in an HTTP header: database passwords such as Postgres, request-signing schemes such as AWS SigV4, and client certificates. If you copy those into a sandbox, the agent can read them.

#Does this work on a Mac?

Yes. Hotcell runs on macOS with Docker Desktop, OrbStack or colima, and can use Apple Virtualization microVMs. On Linux with KVM it can use Firecracker microVMs.

#Do I have to set this up myself to run coding agents?

No. npm install -g directionallylocal then dl sets up Hotcell and Autopilot, our coding agent harness, on your computer or server. Each task runs in its own sandbox and comes back as a pull request.