sclaude / scodex

Run Claude Code or OpenAI Codex CLI in a Docker or Podman sandbox. The CLI runs as it does on the host. It can reach the current directory, one folder for files you hand it, the host state listed below, and the network.

Requirements

macOS or Linux with bash, and a container engine: Docker Engine, Docker Desktop, Rancher Desktop with the dockerd engine, colima, or a podman machine. Rootless podman works through the podman CLI. Rootless Docker is not supported.

Rancher Desktop and colima share only your home directory with their VM. Run from a directory under it, or set SAGENT_SKIP_SHARE_CHECK=1 for a path you shared yourself.

sclaude doctor checks these and names the fix for what it finds.

Install

sclaude ships as two self-contained shell scripts. install puts both in ~/.local/bin without sudo, and adds that directory to your shell startup file if it is missing from PATH. Open a new shell afterwards.

curl -fsSL https://github.com/e6qu/sclaude/releases/latest/download/sclaude -o sclaude
curl -fsSL https://github.com/e6qu/sclaude/releases/latest/download/scodex -o scodex
chmod +x sclaude scodex
./sclaude install

From a clone, ./sclaude install links the scripts, so git pull updates them. install DIR or SAGENT_INSTALL_DIR picks another directory.

The first run builds the sandbox image on your machine, for your user and your settings. That takes a few minutes and about 5.5 GB of disk, with 8 GB free needed during the build. Behind a TLS-inspecting proxy the build takes the proxy's CA from your trust store. If the host does not trust it either, see corporate proxies. Prebuilt images for CI and dev containers are listed under published images.

Update

sclaude update

This updates both wrappers. It also updates Claude Code and Codex in the image whenever either has a new release, even when sclaude itself has none. The two CLIs are the last image layer, so that takes about a minute.

sclaude update --force-rebuild rebuilds the whole image and updates everything else in it to the newest release its source offers: the Ubuntu base image and packages, gh, git, Node.js, Python, Go, Rust and Java within the configured versions, the tool groups (TypeScript, bun, yarn, pnpm; Maven, Gradle, Quarkus, Spring Boot; kubectl, Helm, Terraform, Terragrunt; AWS, Azure and Google Cloud CLIs), and the two agent CLIs. That takes several minutes. A new sclaude version that changes the image rebuilds it on the next run.

From a clone, update leaves the scripts to git pull and updates the image: git pull && sclaude update.

Use

Command	What it does
sclaude	Interactive session. Permission prompts are off (yolo)
sclaude "fix the bug"	Direct prompt
sclaude --continue	Continue the last session in this directory. --resume picks one
sclaude -p "query"	Print mode, no TTY needed
sclaude --no-yolo	Keep the permission prompts
sclaude --no-docker	Turn off nested containers for this run
sclaude shell	Bash in the sandbox for this directory
sclaude mcp add ...	claude mcp add ... inside. Other claude subcommands pass through the same way, apart from the wrapper's own commands below
scodex	The same for Codex
scodex exec "query"	Non-interactive Codex

Every native CLI flag passes through. Yolo means --dangerously-skip-permissions for Claude and --dangerously-bypass-approvals-and-sandbox for Codex. The sandbox limits what that can reach. Security says how far.

Commit before you start and review the agent's changes with git diff.

What the sandbox shares with the host

• The current directory, read-write, at the same path.
• ~/sagent-drop, read-write. Drop a screenshot on the terminal, or paste its path, and either agent can open it. SAGENT_DROP_DIR names another folder.
• Any other folders you list in SAGENT_EXTRA_MOUNTS, read-only unless marked :rw. None by default.
• The clipboard, both ways, text and images. Ctrl+V of a screenshot works in both agents.
• Session transcripts. A conversation can be resumed on either side.
• Your git identity and config, your gh login, and with SSH remotes your ~/.ssh.
• Your sign-in for the agent you run. Signing in inside the sandbox works too.

Containers the agent starts run in the sandbox, on a podman of its own, not on your engine. docker, docker compose and Docker API clients use the sandbox's own Unix socket. Their images are kept in a volume. Buildx and Compose builds use the sandbox's own rootless BuildKit service. Concurrent sandboxes reserve separate persistent stores, including when they run in the same project. --no-docker turns this off. See nested builds and browser tests for dependencies and upgrading older nested storage.

The sandbox runs inside your engine's VM, so a restart of Docker Desktop, Rancher Desktop, colima or the podman machine stops it. The wrapper says so. In a terminal it waits for the engine to come back and resumes the session with --continue. When no engine answers at the start, the error names what is stopped and the command that starts it.

Host state in the sandbox has the details and security has the trade-offs.

What is in the image

Ubuntu with Claude Code, Codex, gh, git and build tools, plus Node.js, Python, Go, Rust and Java. The optional tool groups are js, java, infra and cloud. Toolchain versions and tool selection are configurable; sclaude tools shows the selection. The image lists the contents and covers builds, mirrors and disk use.

Commands

Command	What it does
sclaude update	Update both wrappers and the agent CLIs in the image. --force-rebuild rebuilds everything
sclaude install [DIR]	Put both wrappers on PATH
sclaude shell [args]	Bash in the sandbox. Attaches to a running sandbox for this directory, or starts one
sclaude status	What a run would use
sclaude doctor	Diagnostics, with a fix per finding
sclaude tools	List tools. enable and disable change the selection
sclaude config	Show the settings file. set, unset, get, path
sclaude volumes	Disk use per image and volume
sclaude cleanup	Remove the sandbox images other than the current one
sclaude reset-caches	Clear the npm, pip, apt and nested-container volumes. Credentials and home stay
sclaude reset	Delete every sandbox volume. The workspace, the drop folder, host transcripts and the image stay
sclaude --build	Build the image without running
sclaude dockerfile	Print the Dockerfile a build would use
sclaude version	Wrapper, image, toolchain and tool versions
sclaude check-update	Check for a newer wrapper

Both wrappers have these commands.

Settings

Settings live in ~/.config/sagent/config (under XDG_CONFIG_HOME when set), a bash file that is sourced. sclaude config set KEY VALUE writes it. For the SAGENT_ settings, an environment variable wins over the file. The resource limits are read from the file only.

CPU and memory limits are automatically capped at the engine's capacity. On macOS this is the engine VM's capacity. Each run reports any reduction; the settings file keeps your requested limits for future runs. These limits do not reserve resources across concurrent sessions; see resource limits.

Setting	Meaning	Default
MEMORY_LIMIT	Memory limit, a size like 16g	8g
CPU_LIMIT	CPU limit, a number	4
PIDS_LIMIT	Process and thread limit without nested containers	4096
PIDS_LIMIT_NESTED	Process and thread limit with nested containers	4096
SAGENT_DOCKER	1 for docker and podman inside the sandbox, 0 for none	1
SAGENT_CONTAINER_ENGINE	docker or podman; explicit selection never falls back	docker, then podman
SAGENT_CA_BUNDLE	PEM file with extra CA certificates for the image	unset
SAGENT_GIT_PROTOCOL	ssh or https for GitHub	your gh setting, else https
SAGENT_CLIPBOARD	1 to share the host clipboard, 0 to keep it out	1
SAGENT_DROP_DIR	Host folder mounted read-write at the same path inside	~/sagent-drop
SAGENT_EXTRA_MOUNTS	More host folders, comma-separated, each at the same path inside, read-only unless it ends in :rw	none
SAGENT_SESSIONS	1 to share transcripts, 0 to keep them out, all to share /rewind snapshots too	1
SAGENT_UBUNTU_VERSION	Ubuntu release for the image	26.04
SAGENT_NODE_VERSION	Node.js major version	26
SAGENT_PYTHON_VERSION	Python minor version	3.14
SAGENT_GO_VERSION	Go version, or none	1.27
SAGENT_RUST_VERSION	stable, beta, nightly, a version, or none	stable
SAGENT_JAVA_VERSION	Java major version, or none	26
SAGENT_TOOLS	all, none, group names, or tool names	all
SAGENT_APT_MIRROR	Ubuntu mirror URL for image builds	Ubuntu's archive
SAGENT_AI_ATTRIBUTION	0 keeps Claude Code's commit and PR attribution off. 1 leaves it to Claude's own settings	0
SAGENT_VOLUME_SUFFIX	Suffix on every volume name, for a second set of volumes	none

SAGENT_CONFIG_FILE points at a different file. The file is sourced, so a setting can differ per wrapper:

[ "$SCRIPT_NAME" = scodex ] && SAGENT_SESSIONS=0

Two additional environment controls are not managed by config set: SAGENT_ENGINE_TIMEOUT_SECONDS sets the engine probe deadline (10 seconds by default), and SAGENT_SKIP_SHARE_CHECK=1 bypasses the VM share check for a path you shared yourself.

Uninstall

sclaude reset
for image in $(docker images sagent-sandbox -q | sort -u); do
    docker rmi "$image"
done
rm ~/.local/bin/sclaude ~/.local/bin/scodex

With podman, replace docker with podman. install DIR may have put the wrappers elsewhere; remove them from that directory instead. The PATH block install added to your shell startup file is marked added by sclaude/scodex. The settings file and ~/sagent-drop stay.

Documentation

• Host state in the sandbox: sessions, clipboard, the drop folder, git, gh, ssh, sign-in, MCP servers, attribution.
• The image: contents, versions, tool groups, mirrors, proxies, published images, dev containers.
• Storage layout: volumes and what lands where.
• Security: what the sandbox isolates and what it lets through.
• Testing, releasing, contributing, known issues, changelog.

License

MIT

Copyright 2025-2026 Adrian Mârza.