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.

No image is downloaded. 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

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. Afterwards, review with git diff, then commit or git reset --hard, which discards every uncommitted change.

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.
• 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.

Most of these have a setting that turns them off or narrows them. Host state in the sandbox has the details and security has the trade-offs.

What is in the image

Ubuntu 26.04 with Claude Code, Codex, gh, git and build tools. Node.js 26, Python 3.14, Go 1.27, Rust stable and Java 26. Four tool groups you can drop: js, java, infra (kubectl, Helm, Terraform, Terragrunt) and cloud (AWS, Azure and Google Cloud CLIs). Every version and group is a setting. sclaude tools shows what is in. The image lists everything and covers builds, mirrors and disk use.

Commands

Both wrappers have these commands.

Settings

Settings live in ~/.config/sagent/config, 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.

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

Uninstall

sclaude reset
docker images sagent-sandbox -q | xargs -r docker rmi
rm ~/.local/bin/sclaude ~/.local/bin/scodex

With podman, replace docker with podman. install DIR may have put the wrappers elsewhere. An install from before 2.16 lives in /usr/local/bin. 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, bugs, changelog.

License

MIT

Copyright 2025-2026 Adrian Mârza.