README
¶
A sandboxed runner for any AI agent: isolates your agent in a per-project Docker container with controlled mounts and secret masking. Bring an image with your preferred agent installed — for example, Claude Code or Pi.
What & why
makeslop gives each project its own container launched from a single shared base image. The agent
gets your source tree plus the persistent mounts you explicitly configure: shared directories,
project-local directories, or existing host files/directories. There are no implicit agent-state
mounts or host environment variables; configure mounts under cache and variables under
environments.host. Shared mounts can intentionally expose credentials across projects.
Why use it:
- Isolation — each project runs in its own container; you choose which state to share.
- Secret masking —
.env, PEM keys, and SSH keys are overlaid with/dev/nullbefore launch. - Agent-neutral — run your preferred agent inside the container; makeslop handles the sandbox, not the agent itself.
- Bring your own image — makeslop does not build images. Point it at any image you build or
pull (
makeslop config set image <ref>, or-i/--imageper invocation).examples/claudebox/Dockerfileis a starting point. See Using a custom Docker image.
Requirements
- Docker daemon reachable (via
DOCKER_HOSTor/var/run/docker.sock). - The
dockerCLI binary is not required — makeslop uses the moby/moby Go SDK directly.
Install
Go install (latest):
go install github.com/Zwergpro/makeslop/cmd/makeslop@latest
Prebuilt binaries are published on GitHub Releases for each tagged version (built with GoReleaser).
Quickstart
# 1. Build or pull an image with your preferred agent installed.
# This example uses the included Dockerfile; run from a clone of this repo.
docker build -t agentbox examples/claudebox
# 2. Tell makeslop which image to use
makeslop config set image agentbox
# 3. From your project directory — register the project and seed ~/.makeslop/
makeslop init
# 4. Open an interactive shell in the sandbox
makeslop run
# 5. Inside the container, launch the agent installed in your image
Use your own Dockerfile to install the agent and tools you need. The included Dockerfile is only an example, not a required image or agent choice.
The image has no default. If none is configured, run fails, status reports ✗, and init
prints a note — each pointing at makeslop config set image <ref>. Override the configured image
for one invocation with -i/--image (makeslop run -i myimage:dev). makeslop never pulls images:
a missing local image fails with a "build or pull it" hint (e.g. docker pull <ref>).
How it works
┌─ your terminal ──────────────────────────────────────────────────────────────┐
│ makeslop run │
│ │ scans for secrets (masks with /dev/null) │
│ │ mounts project root + explicitly configured caches │
│ ▼ │
│ ────────────────────────────────────────────────────────────────────────── │
│ agent container --cap-drop ALL --security-opt no-new-privileges │
│ │
│ /workspace/<name> ← your project root (bind-mounted) │
│ /home/user/agent-state/ ← only if cache.shared requests agent-state │
│ /tmp ← tmpfs (default 100m, not on disk) │
└──────────────────────────────────────────────────────────────────────────────┘
By default the container has normal Docker bridge networking and full internet access. Set
network_mode or networks in .makeslop.yaml to change that (for example, route all traffic
through a container:proxy sidecar); see Configuration and
docs/reference.md.
Configuration
makeslop init creates a .makeslop.yaml at the project root. Edit it to control secret masking
and directory/file exclusions. Persistent mounts are opt-in, for example:
cache:
shared: [agent-state] # ~/.makeslop/shared/<name> -> /home/user/<name>
local: [docs] # workspace cache -> container project/docs
static:
- "~/.config/agent:~/.config/agent" # existing agent config directory
- "./tools:/opt/tools" # existing project-relative directory
Missing shared/local directories are created on real runs. Static sources must already exist;
files mount as files and directories as directories. Empty or missing cache mounts nothing.
See cache layout and path rules.
Exclusion example:
exclude:
scan:
patterns:
- "*.env"
- ".env.*"
- "*.pem"
- "*.key"
- "*.p12"
- "*.pfx"
- "*.tfstate"
- "id_rsa*"
- "id_ed25519*"
- ".npmrc"
- ".netrc"
- ".git-credentials"
- ".pypirc"
- ".htpasswd"
- "service-account*.json"
- "kubeconfig"
- "*.kubeconfig"
skip-dirs:
- .git
- node_modules
- vendor
- .venv
dirs: [] # mount these as empty tmpfs inside the container
files: [] # overlay these with /dev/null inside the container
Inject environment variables into the container with an environments: block — fixed values under static, names to copy from the host under host:
environments:
static:
HTTP_PROXY: "http://192.168.1.1:11111"
host:
- GITHUB_TOKEN
Static values must be scalars; numbers and booleans are coerced to strings. Host names are copied under the same name; unset ones are skipped. Absent block = no -e flags. See docs/reference.md for the full spec.
Choose the container's network with network_mode or networks (compose names; set one, not both):
network_mode: "container:proxy" # bridge | host | none | container:<name|id> | <network>
# or:
networks: [myapp_default]
makeslop only attaches: it never creates networks or containers. A missing network, or a
container: target that is missing or not running, fails run's pre-flight and the status
network row. Absent keys = Docker's default bridge. See
docs/reference.md.
Global settings (~/.makeslop/settings.json) control the image (required, no default), shell, and /tmp size:
makeslop config set image agentbox
makeslop config set shell /bin/zsh
makeslop config set tmp_dir_size 100m
Security at a glance
Secret masking is config-driven: patterns in exclude.scan.patterns are basename globs; matched
files are overlaid with /dev/null so the agent sees a zero-byte file instead of the real secret.
Walk errors are fatal — if makeslop cannot prove a directory is secret-free it refuses to launch.
See docs/security.md for the full masking spec and home-directory guard.
Scan patterns must be basename globs (e.g. *.pem); a pattern containing / (e.g.
secrets/*.pem) is a hard error at load time. .makeslop.yaml must be a regular file: a symlink
is rejected by run and init (status shows the error as a secret-scan warning and fails the
blocking network row, so it reports not ready).
Commands
| Command | What it does |
|---|---|
makeslop init |
Register project, seed ~/.makeslop/ |
makeslop run |
Launch an interactive agent container (TTY required) |
makeslop status |
Ordered readiness check: daemon, config, image, workspace, secrets, network |
makeslop config |
View or set global settings (image, shell, tmp_dir_size) |
makeslop ls |
List registered workspaces |
makeslop remove <name> |
Unregister a workspace and delete its cache directory |
makeslop version |
Print the build version |
makeslop run --dry-run prints the equivalent docker run command without launching.
run and status accept -i/--image <ref> to override the configured image.
makeslop run -j <path>[:ro] also mounts another makeslop project next to the current one; see
Joined projects.
Documentation
- Command & Runtime Reference — all flags, mount table, exit codes, settings schema
- Security — secret masking, egress model, home-directory guard
- Architecture — design patterns, module boundaries, contributing
License
MIT