Skip to main content

​
Containerization

Atomic runs with all permissions by default. To restrict which directories it can write to and what it can access, choose one of two approaches:
  1. Run the whole atomic process inside an isolated environment.
  2. Run atomic on the host and route tool execution into an isolated environment.
Containerization is the outer boundary, not the only one. Security covers the project-trust prompt that gates which project-scoped extensions, skills, and settings load in the first place; read it alongside this page when you are deciding what an untrusted repository is allowed to do.

​
Choose a pattern

Extensions run wherever the atomic process runs. If you run host atomic with a tool-routing extension, other custom extension tools still run on the host unless they also delegate their operations.

​
Gondolin

Gondolin is a local Linux micro-VM. Use the example extension when you want atomic on the host with selected file tools and shell execution routed into the VM. This is not isolation for the entire session. Setup:
Run from the project you want mounted:
The extension mounts the host cwd at /workspace in the VM and overrides read, write, edit, bash, find, and ls. User ! commands are routed into the VM, as well. File changes under /workspace write through to the host. search remains a host tool; it is not redirected into the VM. The removed grep tool is not registered. For guest-only content searches, use a shell command through the routed bash tool or ! command. To expose only these routed tools, start with atomic --tools read,write,edit,bash,find,ls -e ~/.atomic/agent/extensions/gondolin; other loaded extensions can still supply host-side tools. Use whole-process isolation instead when host filesystem access must be prevented. Requirements: npm for dependency installation, Node.js >= 23.6.0 for @earendil-works/gondolin, plus QEMU (requires installation through your package manager).

​
Plain Docker

Run the whole atomic process in Docker when you want the simplest local container boundary. Dockerfile.atomic:
For an image without Node.js or npm, use the release-archive installer instead:
The archive path installs the full prebuilt payload and needs no JavaScript runtime or package manager. The other packages in this example support Atomic’s shell and common coding tasks. Build and run:
The -v "$PWD:/workspace" option mounts your current directory at /workspace in the container. Reads and writes in /workspace directly affect your host files, as in the Gondolin example. Use a named volume for /root/.atomic/agent if you want container-local settings and sessions. Mounting your host ~/.atomic/agent exposes host auth and session files to the container.

​
OpenShell

Use NVIDIA OpenShell when you want a policy-controlled sandbox with filesystem, process, network, credential, and inference controls. OpenShell can run sandboxes through a local gateway backed by Docker, Podman, or a VM runtime, or through a remote Kubernetes gateway. Every sandbox requires an active gateway. Register and select one before creating a sandbox:
Launch atomic inside an OpenShell sandbox:
In this pattern, the whole atomic process runs inside the sandbox. Built-in tools, ! commands, and extension tools execute inside the OpenShell boundary. If the gateway is remote, project files are not bind-mounted from the host, meaning writes in the sandbox are not reflected on your machine. Clone the repository inside the sandbox or use OpenShell file transfer commands:
OpenShell providers can keep raw model API keys outside the sandbox. When inference routing is configured, code inside the sandbox can call https://inference.local, and the gateway injects the configured provider credentials upstream. Configure Atomic to use the corresponding OpenAI-compatible or Anthropic-compatible endpoint if you want model traffic to use this route.