locki 0.0.8

AI sandboxing without the taste of sand

Locki is the first sandbox I've used where I genuinely forget I'm in one — until I try something I shouldn't.

⸺ Claude Code (Opus 4.6)

L	O	C	K	I
ᛚ	ᛟ	ᚲ	ᚴ	ᛁ

AI sandboxing without the taste of sand

 

Locki is a CLI that safely runs AI agents with all permissions bypassed in isolated worktrees.

❌ without Locki	✅ with Locki
git worktree add -b fix-42 ../fix-42 cd ../fix-42 claude "fix issue #42" # ...wait a few seconds # ...approve a command # ...wait a few seconds # ...approve another command # ...different agent rebuilt the image # and caused a name clash‽ # ...something is hogging the port‽ # ...approve another command # ...	locki x claude "fix issue #42" # ...go make a cup of tea # ...drink tea 🍵 # ...look, the PR is ready

 

Locki gives you:

• Maximum UX (user experience): no permission prompts, isolated worktrees automatically managed.
• Maximum AX (agent experience): run real-world software, including systemd, Docker, or Kubernetes.

 

How is Locki different than other sandboxes?

Others run either:
a) full VM per sandbox: resource-heavy and slow to start
b) OS-level jail (Landlock, Bubblewrap, etc.): not isolated (ports collide, image tags get overwritten, etc.)
c) OCI container / microVM: limited support for background services (i.e. no systemd), containers, Kubernetes, ...

Locki runs Incus containers (full OS) inside a single shared VM. While the VM layer isolates host from AI mischief, Incus containers are a lightweight layer on top to isolate sandboxes from each other. Spawn a real non-micro OS in <5s and run anything in it.

Furthermore, Locki protects your Git history from tampering while still allowing safe operations like commits to the worktree branch. Be able to fall back on earlier commits when an agent goes haywire, while not giving up the convenience of arriving at a fully baked pull request.

Case study: Kagenti ADK uses Locki to run a full MicroShift node, allowing agents to verify their work using E2E tests on a real cluster. Something breaks? The agent can kubectl right in and debug, all contained within the Locki sandbox.

 

How to install and use Locki?

1. Install: uv tool install locki. (Install uv first if you don't have it.)

2. If you're on Linux, also install OpenSSH (usually preinstalled) and QEMU.

3. cd to your Git repository and run: locki ai

   (Use locki x alone to open a regular shell instead.)

4. First start takes longer, wait a few minutes for the VM to boot.

5. Follow prompts to log in to the AI CLI. Login will be persisted across sandboxes.

6. Build! Your agent is already instructed on how to behave in the sandbox.

7. Run locki ai again to open an interactive selector: continue existing session, or start a new one.

8. Once happy, commit and push your changes. Ask the agent, or do this manually for more control.

9. After merging the branch, just delete the worktree from your IDE and Locki will clean up the sandbox.

   (Or do it manually with: locki rm)

 

Pro-tips for power users

• locki x opens an interactive picker to select an existing sandbox or create a new one. Use locki x -n to create a new sandbox non-interactively. Use locki x -b <substring> to match an existing sandbox by any part of its branch name (e.g. the branch name or the 8-char ID). cd to a worktree folder (~/.locki/worktrees/...) to operate on it directly.

• Editors like VSCode show worktrees in the sidebar, useful as a quick UI for reviewing and modifying changes. (⚠️ VSCode 1.115.0+ requires setting "git.detectWorktrees": true for this to work.)

• Locki sandboxes provide Mise for tool version management -- replacing nvm, rbenv, brew etc. with a single tool. To make your agents' (and humans') lives easier, optionally (ask your agent to) create mise.toml with tool versions and project tasks.

• Want to use custom AI configuration in the VM -- instructions, skills, MCP servers, ...? Sandboxes share a home folder accessible at ~/.locki/home on host. For example, you can run cp ~/.claude/CLAUDE.md ~/.locki/home/.claude/CLAUDE.md to copy your custom instructions for use in sandboxes.

• Forward ports from a sandbox to your host: locki pf -b <substring> 8080 or locki pf -b <substring> :3000 for a random host port. Use --clear to remove all forwards. Agent in sandbox can forward via self-service, just ask them.

• Using Git hooks? Locki worktrees are automatically configured to run these inside the sandbox, even if you run git from outside. You won't be surprised by a .venv or node_modules containing incompatible binaries.

• Something is broken? Try locki vm delete -- it will preserve your worktrees and settings in ~/.locki, but the VM will be recreated from scratch on next run.

• Sandboxes run on Fedora 43. Want a different OS? Create a locki.toml file referencing either an available OS image, or a local Incus rootfs tarball by path. Example:

  # locki.toml
  
  [incus_image]
  aarch64 = "ubuntu/questing"
  x86_64 = "ubuntu/questing"
  

  (Since containers share a binary cache, it is not recommended to mix musl distros (like Alpine) with regular ones.)

 

Notes on security

Locki uses a single Lima VM which can only access the ~/.locki/worktrees and ~/.locki/home folders, which forms the security boundary. The sandboxed programs can read and write to these folders, and also access anything on the internet and local network. Furthermore, an allowlist of git and gh commands is used to offer a guest-to-host SSH server. .git files are checked for tampering when hooks are executed against them.

Locki is designed to provide protection for the host operating system and files from being messed up by a malfunctioning AI agent. There is no exfiltration protection, so be aware that API keys exposed to the agents need to be treated as potentially exposed and disposable, with limited scope. (This is no different from running the agent locally, just specifying that Locki does not help here. Use a dedicated solution like OneCLI if interested.)

Despite best effort, Locki provides no security guarantees and is provided "as is". That's the legal speak for "this is a random project by a random dude provided for free", you can't expect corporate-paid-support level security assurances. Random dude believes that while not perfect, using Locki is better than many existing sandboxing solutions and certainly better than going full --yolo on your bare machine and hoping for the best.