How it works

Run AI agents in an isolated, fully controlled environment. An agent gets access to nothing unless you explicitly grant it — and everything it is granted is monitored and logged.

In Contained you set up an agent once — which agent, which of your folders it may see, which servers it may reach, which API key it uses — and then start it with one click. The agent runs in a container (a sandbox) where:

• only the folders you grant exist — nothing else of your computer;
• only the servers you grant can be reached — everything else is blocked;
• every file operation in a granted folder and every request through the sandbox's only exit, allowed or blocked, is recorded in a log you can watch live.

Isolation is structural, not cooperative: the agent cannot opt out.

Ready-made settings come with the application for Aider, Claude Code, Gemini CLI, OpenAI Codex CLI and OpenCode (see Supported agents); any other command-line agent can be set up by hand. The agents are not part of the download: the application installs them from their official sources into container images on this computer, on the first start of a sandbox that needs them. Every agent works with your own account at its provider.

New here? Follow Getting started — from the download to a running agent, step by step.

Getting started — step by step

From the download to a running agent that sees only your project folder — about fifteen minutes, most of it waiting for downloads.

1. Install Docker Desktop

   Agents run in Linux containers, which Docker Desktop provides. Download it from docker.com, install it with the WSL2 backend it suggests, start it once and accept its terms.

   After that you do not need to start it yourself: Contained starts Docker Desktop in the background when it needs it. If Docker Desktop is missing, Contained says so and links to the download.

2. Install AxioLogic Contained Agents

   Download the installer, Contained-Setup-1.3.2.exe, from the Download page of the website and run it. It installs for your user only — no administrator rights — and adds a Start Menu entry. It checks for Docker, installs the Microsoft Edge WebView2 runtime if Windows lacks it, and offers to add the contained command-line tool to your PATH.

   A newer version replaces the installed one in its folder — it is never installed next to it — and keeps your sandboxes, keys, logs and chat history. The installer says which version it replaces: Ready to Update, from the installed version to the new one. About, at the top of the window, shows the version that runs.

3. Get an API key

   Create an API key at the provider of your agent and copy it — for example OpenAI (Codex CLI): platform.openai.com → API keys; Anthropic (Claude Code, and Aider and OpenCode as set up here): the Anthropic Console → API keys; Google (Gemini CLI): Google AI Studio → Get API key.

   The key is stored encrypted on your computer and handed only to the agent. It never appears in exported configurations or in logs.

4. Create a sandbox

   Start AxioLogic Contained Agents from the Start Menu. If Docker Desktop is not running yet, a blue banner shows until it is ready — a cold start takes up to a minute. Click New sandbox: a guide of four pages opens, and most of it is filled in for you.

   • Agent — the first agent installed on this computer is chosen; choose another in the list if you like. Paste your API key.
   • Folders — click Choose… and pick your project folder. The agent sees it and nothing else of your computer; the sandbox is named after it.
   • Network and Limits — already set for your agent.

   Click Save. If something is missing, the guide says what and where. Every page is described in The sandbox editor, page by page.

5. Start the agent

   In the sandbox's row click Start agent. The first start installs the agent into its container image, which takes a minute or two; later starts take seconds. The agent's console opens at the bottom of the window — work with the agent there as in any terminal. Agents with a conversation interface (so far Claude Code) can also be used in the Chat view.

6. Watch what it does

   Click Show log. Next to the console you see every file the agent opens, creates, changes or deletes in your folder, every server it tries to reach — allowed or blocked — and every error the application reported for the sandbox. Choose DENY only to see just what was blocked.

7. Allow more, if needed

   If the log shows the agent was blocked from a server it really needs — for example registry.npmjs.org to install packages — click Edit, go to the Network page, tick the matching common need or add the server under Other servers, click Save, then Stop and Start agent. Nothing is reachable unless you allow it.

8. Keep the setup (optional)

   Export YAML saves the sandbox as a short document — without the key — that you can review, keep in version control and apply on another computer with contained apply -f (see YAML and infrastructure as code).

The sandbox editor, page by page

A sandbox is one configured agent: the agent program plus everything it is allowed to do. New sandbox creates one and Edit changes it; both open the same editor, a guide of four pages: Agent Folders Network Limits. The panel on the left lists them — click a page to go there — and Next and Back move through them in order. Save (top right, and at the end of the last page) works from any page; Cancel leaves everything as it was.

If something is missing when you click Save, the editor goes to the page in question, says what is missing and marks the page with a red dot. Nothing is saved until everything is in order.

Page 1: Agent

• Name — how the sandbox appears in the list and in the log. One is suggested — after the agent, then after the project folder — and you may type another: whatever you type becomes lowercase letters, digits and hyphens. The name cannot be changed later.
• Agent — the list shows every supported agent. Those installed on this computer can be chosen; the others are shown in grey (see Supported agents). Other agent (set up by hand) is for an agent of your own, set up in Advanced settings.
• API key — the field is named after the provider, for example Anthropic API key, with a link to where you create one. The key is stored encrypted on this computer and given only to the agent; it never appears in exports or logs. The chip shows no key yet, will be stored (on Save) or stored. A stored key is never shown again: type a new one to replace it, or click Remove the stored key. A sandbox can be saved without a key, but its agent does not start until it has one.
• Advanced settings (folded) — what the list fills in for an agent: image, command, working directory, fixed settings and further keys. They are needed only for an agent of your own or for special options, and open by themselves then; see Advanced settings.

Page 2: Folders

The agent sees only the folders listed here — nothing else of your computer. The first is the project folder: the agent starts in it.

• Folder on this computer — click Choose… and pick it in the usual Windows dialog, or type its path.
• Network drives — a folder on a network drive (a NAS, a drive connected as X:, a \\server\share path) is connected directly; nothing is copied. Under it, enter your login for its server — the one Windows asked for when the drive was connected — or leave it empty to connect as guest, which is enough where the drive is shared with everyone. The login is stored encrypted on this computer, once per server, for every sandbox; it is saved with the sandbox. While a sandbox exists, Docker keeps the login in the settings of its connection to the drive, inside Docker Desktop's machine.
• Inside the sandbox — where the agent finds the folder. It is filled in for you: /work for the project folder, the folder's own name for the others (/docs, for example). Change it only if the agent needs a particular place.
• Allow changes — ticked, the agent may create, edit and delete files in the folder; not ticked, it may only read them. It is ticked for the project folder and not for the folders you add.
• Record in the log — Every access: every file operation, including opening a file to read it; Only changes: creating, writing, renaming and deleting; Nothing: no records for this folder (a plain folder, slightly faster).

+ Add another folder adds one; Remove takes one away. Without any folder the agent sees nothing of your computer and starts in an empty folder.

Page 3: Network

The agent can reach only the servers allowed here; every other connection is blocked and appears in the log as DENY.

• Needed by … — the servers your agent cannot work without. They come with the agent and are always allowed. If one is missing — in a sandbox made from YAML — the page says so and offers Allow.
• Common needs — tick what the agent should be able to do: install JavaScript packages (npm), install Python packages (pip), download code from GitHub. Each tick allows the servers named next to it.
• Other servers — anything else: the server's name, for example api.example.com — a pasted web address is shortened to it; *.example.com allows every subdomain of example.com, but not example.com itself — and its ports: 443, the usual one (HTTPS), is filled in; several are separated by commas.

The log records host, port, verdict and time of every request that reaches the sandbox's proxy — never the content.

Page 4: Limits

• Processor cores — how many the agent may use, from 1 up to all that Docker has, or no limit. 2 are plenty for most work.
• Memory — how much the agent may use, from 1 GB up to all that Docker has, or no limit. 4 GB suit most projects; if the agent stops during heavy work, give it more.

The lists end at what Docker has for all sandboxes together, which the page shows; with Docker Desktop that is usually less than the computer has. A value set in YAML that is not in a list is kept and shown as it is.

Advanced settings

Folded, on the Agent page. For the agents in the list, everything here is filled in when the agent is chosen. It opens by itself for an agent of your own and when a sandbox's settings differ from what the list fills in.

Changing an agent (Edit)

1. Open the editor

   Click Edit in the sandbox's row. The same four pages open with the current settings; the name is fixed.

2. Change what you need

   Go straight to the page in the panel on the left. A stored key shows stored and an empty field: leave it empty to keep the key, type a new one to replace it, or click Remove the stored key.

3. Save

   Click Save, from any page. Cancel leaves everything unchanged.

4. Restart a running agent

   A running agent keeps its old settings until it restarts; its row shows config changed — restart. Click Stop, then Start agent.

Recipes

When Save refuses

Save checks every page first. What is missing is named on its page, in a red box, and the page gets a red dot in the panel on the left; nothing is saved until everything is in order. The most common:

The same rules apply to contained apply, which names the field in the YAML instead: filesystem.grants[0] is the first folder, network.grants[1] the second server, and so on.

Starting and the console

Each sandbox row has these buttons:

Badges next to the status: config changed — restart — settings were edited while the agent runs; API key missing — the agent cannot start until you enter its key under Edit, on the Agent page; cannot start — the configuration cannot be used as it is on this computer, usually because a granted folder no longer exists (hover for the reason, correct it under Edit); audit problem — log records could not be stored (hover for the reason, which is also in the log under errors; the records are kept and stored once the cause is gone).

Copy in the console: select text, then Ctrl+C or right-click. Without a selection Ctrl+C interrupts the agent, as in any terminal. If the agent's screen uses the mouse (Codex does), hold Shift while selecting. Paste: Ctrl+V, or right-click with nothing selected.

The agent's home folder inside the sandbox (its settings and conversation history) is kept between starts and deleted with the sandbox.

Chat

For Claude Code sandboxes, Chat opens a claude.ai-style conversation with the agent working in the sandbox: streamed answers with formatted code, every tool call shown as an expandable chip (file edits as red/green diffs), duration and cost per turn. The sidebar lists past conversations — switch, continue or delete them. Stop interrupts a turn; paste images straight into the message box.

The chat runs Claude Code inside the same sandbox — same folders, same network grants, same log. Its permission prompts are skipped: the sandbox is the containment.

A link in an answer opens in your web browser, never in the Contained window. The window loads nothing an answer names: a picture appears as a link (🖼 and its name). So nothing in an answer reaches the internet past the sandbox unless you open one of its links.

The log

Show log in a sandbox's row shows its log next to the console; Logs at the top of the window shows all sandboxes. Tick errors, files and network in any combination. More filters: sandbox, DENY only / ALLOW only (network) and a path search (files).

• A network row is one request that reached the sandbox's proxy: time, sandbox, ALLOW or DENY, host, port. A program that tries to go around the proxy gets no connection at all — the sandbox has no other way out — and such an attempt leaves no row.
• A file row is one operation in a granted folder: open for reading or writing, create, delete, rename, make or remove a folder, truncate — with path and result, including failures.
• An error row is an error the application reported: a start, stop or deletion that failed, an audit problem (the badge's reason), Docker Desktop that could not be started — with time, sandbox (— when it concerns none) and the message. Passwords in messages are masked.

Records older than 30 days are deleted automatically by the application (the CLI deletes nothing). Chat history is kept.

Supported agents

The Agent list shows every agent below. Those installed on this computer — found on the PATH or in the usual npm, nvm and pipx locations — come first and can be chosen; the others are shown in grey. A sandbox made elsewhere keeps its agent even when it is not installed here.

• The sandbox never runs the copy installed on your computer. Each agent runs from its own image, contained/agent-<id>, built on this computer on the first start of a sandbox that uses it, on top of contained/agent-base (a common toolchain, no agent); the agent is installed into its image from its official source (npm, PyPI). An image is rebuilt when Contained ships a changed one, so the first start after an update may take a moment longer.
• Codex CLI takes its key from a login rather than from the environment, so its image registers the key as a Codex login at every start. It also starts Codex with its own command sandbox off: that sandbox (bubblewrap) cannot work inside a container. The Contained sandbox is the containment; Codex's approval prompts stay.
• Servers and settings of every agent follow its documentation. If an agent needs more, the log shows what it tried to reach (Recipes).
• Other agent (set up by hand): any Linux image containing a command-line agent can be set up in Advanced settings. Such an image must already exist in Docker; Contained builds only its own.

Docker

While Docker is not usable, the sandbox list shows one banner and the buttons that need Docker are grey:

What Contained guarantees — and what it does not

YAML and infrastructure as code

Every sandbox is one YAML document; the form and the YAML are two views of the same configuration with the same checks. Export YAML saves it; contained apply reproduces it on any machine — byte-identical. Keys are not part of it: enter them again on the other machine.

apiVersion: contained/v1
kind: Sandbox
metadata:
  name: claude-dev                     # Agent → Name
spec:
  image: contained/agent-claude-code:latest  # Advanced settings → Image
  agent:
    command: ["claude"]                # Advanced settings → Command
    workdir: /work                     # Advanced settings → Working directory
    env:
      set:                             # Advanced settings → Fixed settings
        CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
      secrets: ["ANTHROPIC_API_KEY"]   # the API key's variable (names only, never values)
  filesystem:
    grants:                            # Folders
      - hostPath: "C:/Projects/MyProject"
        mountPath: /work
        mode: rw
        log: full
  network:
    default: deny
    grants:                            # Network
      - host: api.anthropic.com
        ports: [443]
        log: metadata
      - host: platform.claude.com
        ports: [443]
        log: metadata
  limits:                              # Limits
    cpu: "2"
    memory: 4Gi
  onViolation: log                     # reserved; no effect in v1

contained plan  -f my-sandbox.yaml     # what would change: CREATE / UPDATE / no changes
contained apply -f my-sandbox.yaml     # create or update the sandbox
contained export my-sandbox            # print the stored YAML

Unknown fields are rejected, so a typo cannot silently weaken a sandbox. A definition from version 1.1 or earlier that runs claude on contained/agent-base:latest — where Claude Code used to be — is read with Claude Code's own image, contained/agent-claude-code:latest.

CLI reference

Deleting a sandbox is done in the application.

Linux (command-line only). Set hostPath in the example to a folder on this machine, then:

tar xzf contained-1.3.2-linux-amd64.tar.gz && cd contained-1.3.2-linux-amd64
./bin/contained apply -f examples/claude-dev.yaml             # store the configuration
./bin/contained secret set claude-dev ANTHROPIC_API_KEY       # paste the key, Enter
./bin/contained run -f examples/claude-dev.yaml               # start and attach to the agent

On Linux keys are stored unencrypted in the Contained database, protected only by the permissions of the data folder (created 0700).

Logging semantics (precise)

• Network: the sandbox has no way out except the Contained proxy. Every request that reaches the proxy — allowed and denied — is recorded: sandbox, host, port, verdict, timestamp. The host is the target named in the CONNECT request (the proxy does not read the TLS handshake, so not the SNI); contents are never inspected. A direct attempt that bypasses the proxy fails — there is no route — and is not recorded.
• Filesystem: audited folders are served through a FUSE layer; the real host data lives in a root-only staging area the agent cannot reach. Logged per operation: open (as open_r/open_w/open_rw intent), create, unlink, rename (with destination), mkdir, rmdir, symlink, link, truncate — with path and result, including failures. log: metadata drops read intent; log: off bypasses auditing (plain mount).
• Inside the sandbox an ungranted path does not exist — there is no “denied attempt” event for it. Attempt-level auditing exists on the network side (for requests that reach the proxy); operation-level auditing in granted folders.
• The trail survives failures: its sources are kept until their records are stored, and stopping or deleting a sandbox stores the rest first (if that fails, nothing is removed and the action reports it). Records carry a run id and a sequence number, so reading a source twice never duplicates them; a record that cannot be stored is retried, never skipped. When the audit layer of a granted folder cannot write its records, the folder refuses every further operation.

Security notes

• The application is a local desktop program: nothing listens on the network — one machine, one user.
• Both sandbox containers drop all Linux capabilities (the audit layer adds back a minimal set) and run with no-new-privileges; the proxy runs unprivileged on a read-only root filesystem.
• Inside a sandbox, agent safeguards that would duplicate the sandbox or cannot work in a container are off: the chat runs Claude Code without its permission prompts, and Codex runs without its own command sandbox. The Contained sandbox is the containment in both cases.
• Keys never go into configurations, exports or logs. On Windows they are DPAPI-encrypted; on Linux they are not encrypted. The log store is plain SQLite on your disk — protect the machine.
• Logins for network drives are stored like keys. To connect a drive, Contained hands the login to Docker: it stays in the settings of the drive's connection, inside Docker Desktop's machine, until the sandbox is started again or deleted. The agent cannot read it.
• Contained starts Docker Desktop when it is needed and minimizes the window Docker opens on that start; it never closes Docker's windows or changes its settings.
• Out of scope in v1: microVM isolation, multi-user/remote access, byte-level I/O tracing, TLS interception.

Data locations

%USERPROFILE%\.contained\ (override with CONTAINED_DATA_DIR):

• contained.db — SQLite with sandbox configurations, keys, network drive logins, logs and chat history. Treat it as read-only while Contained is running.
• webview2\ — the application window's browser profile.
• fsevents\, collector\, bin\ — internal plumbing.

In Docker: one volume per sandbox, contained-home-<name>, holds the agent's home folder; the images contained/agent-* hold the agents. Uninstalling Contained leaves all of this in place.

Troubleshooting