slot

Parallel, isolated working environments for AI agents.

slot init                  # set up
slot create 1              # spin up a fresh sandbox
slot start 1               # open Claude Code in it
slot diff 1 my-feature     # review what the agent did
slot push 1 my-feature     # send the branch back to your real repo
slot teardown 1            # clean up

Each slot is a separate Docker microVM with its own clones of your projects. Agents work inside; your real code stays clean. Two modes: default (fast, for personal projects) and safe (audit log, staging buffer, scrubbed env, redacted-secrets allowlist — for production code).

Install

uv tool install ./slot-0.3.3-py3-none-any.whl
# or pipx install ./slot-0.3.3-py3-none-any.whl
# or pip install --user ./slot-0.3.3-py3-none-any.whl

Requires Python 3.11+, git, and sbx (Docker's sandbox CLI). On Linux, /dev/kvm accessible. See docs/01-getting-started/installation.md.

New here?

Read GUIDE.md — a plain-English, example-first walkthrough of every feature (including running multiple repos in one slot).

Documentation

Full docs are in docs/. Quick links:

• What is slot? — 2-minute mental model
• Your first slot — end-to-end walkthrough
• Concepts — glossary
• Default mode / Safe mode — the two workflows
• Secrets — the .agents redacted-marker rule
• Hooks — extending slot
• Integrations — wiring host services into sandboxes (Plyn walkthrough)
• Commands reference
• Why this shape — design choices
• Threat model

What's new in 0.3.3

• Renamed TaskFlow to Plyn throughout the docs, integration walkthrough, and starter pack — same app, new name. Existing slot projects need no changes; only the host-side container, volume, and skill names rebrand.
• Integration doc is now docs/02-using-slot/integrations/plyn.md
• Starter pack is now plyn-starter-pack/, with setup.sh accepting env-var overrides so legacy taskflow-data volumes can be migrated in-place — see the pack README

What's new in 0.3.2

• Per-project branch in sandbox.toml — pin slots to a specific branch instead of inheriting whatever was checked out on the host
• Per-project skills = [...] in sandbox.toml — curate which ~/.claude/skills/ entries get copied into slots; omit for the current "copy everything" behaviour
• slot create prints the actual branch checked out for each cloned project — no more guessing
• Wizard input forgiveness — typing Y or N into path prompts is now detected as "yes use default" / "no skip", instead of being taken as a literal one-letter path
• Plyn integration documented — new docs/02-using-slot/integrations/plyn.md walks through the full setup, with a starter pack for one-command install
• 126 tests, up from 90

What's new in 0.3.1

• Unified [[project.secrets]] block replaces the single env = field — supports redacted env files, service account keys, certs, whatever
• Allowlist policy for safe mode: secret host filenames must contain .agents (e.g. .env.agents, .keys/sa-key.agents.json)
• Backwards compatible — old env = "..." configs still work, with a deprecation note
• 90 tests, up from 67
• Docs split into 24 focused files instead of three big ones

See docs/02-using-slot/secrets.md for the secrets story end-to-end.

Status

v0.3.1 — feature-complete for the core loop. See what we said no to for things that aren't planned.

License

MIT