curl -fsSL https://gitea.dideric.is/didericis/bot-bottle/raw/branch/main/install.sh | sh
bot-bottle doctor # check Docker / backend prerequisitesThe bottle is enforced by the gateway, outside the sandbox — so a hijacked agent can rewrite its own prompt, but never its own boundary.
Define who your agent is and what it does.
~/.bot-bottle/agents/implementer.md
You are a feature-implementation agent running inside an ephemeral
bot-bottle sandbox. Implement only what your task prompt asks for. Don't
refactor adjacent code, invent follow-ups, or relax the PRD's non-goals.
Commit early and often with Conventional Commits — the host expects a
clean working tree when you report back. If anything is ambiguous, stop
and report rather than guessing.
The repos you can reach are the remotes configured in ~/.gitconfig, all
behind git-gate, which runs gitleaks on every push. Push code through the
git remote — don't use forge file-edit APIs to publish changes unless the
host tells you to bypass git-gate.Define a set of boundaries (the bottle) for agents to work in.
~/.bot-bottle/bottles/claude-dev.md
---
agent_provider:
template: claude # inherit the Claude provider boundary
auth_token: BOT_BOTTLE_CLAUDE_OAUTH_TOKEN
git-gate:
user:
name: claude
email: claude@example.com # commits are attributed to this identity
egress:
routes:
- host: git.example.com # the project's git host, for git-gate
inspect:
auth:
scheme: token
token_ref: BOT_BOTTLE_GIT_TOKEN
# Long-lived Claude control channel — DLP off so a single frame
# match can't tear down the WebSocket (Anthropic-owned host).
- host: bridge.claudeusercontent.com
inspect: false
---
A Claude-provider development bottle. Commits are attributed to the
`claude` git identity, and egress is scoped to the Anthropic API (via the
provider template), the project's git host, and PyPI for pip installs.Start an agent. bot-bottle builds the sandbox image on first run and drops you straight in — then watch it catch a leak.
bot-bottle start implementer --bottle claude-dev # builds the image on first run, drops you in
Agent harnesses aren't enough. Leaked keys and infrastructure damage happen regularly, not in isolated incidents. A sample of publicly documented cases:
Not one incident. An entire pattern.
Deleted or wiped despite explicit instructions not to touch them.
Home directories wiped by a single overreaching cleanup command.
~/ in a cleanup command, breaking
authentication across every app on the machine.
Incident report
Egress limits, sandboxing, and DLP scanning aren't enough by themselves: you need all three. That's exactly what a bottle is built to contain: an egress allowlist means an agent can't reach a host or database that isn't declared in its manifest, a sandboxed filesystem means a wipe command destroys the bottle's own throwaway files instead of the developer's real machine, and blind credential injection with outbound secret scanning means the agent never holds a real key to leak in the first place.
Open source and tested: 84% test coverage, 95% on core security modules, 5 exfiltration techniques covered by a standing red-team suite. See the tests
The agent process itself runs inside gVisor, Apple Container, or a microVM. A compromise has to break the sandbox, not just guess a hidden key.
The allowlist is the real boundary; this is the backstop on the hosts you did allow. Requests are scanned for known tokens, secret patterns, and planted canaries — matches get redacted, blocked, or held for a human to approve.
View sourceOnly declared hosts, methods, headers, and path shapes get through the proxy.
One layer of the seal, not the whole story: host tokens stay outside the agent, which sees proxy URLs instead of raw credentials.
Git remotes route through git-gate so refs are scanned before they reach upstream.
View source
Each bottle declares its own skills, environment, git
identity, and route policy, and extends lets you
layer task-specific policy on top of a shared provider
baseline.
Bottle definitions live under ~/.bot-bottle/bottles/, outside the repo. A malicious clone can't redirect a route or rewrite its own policy.
View PRDA blocked agent can request a new route. A human approves or denies before any traffic moves.
Launch as many bottles as you want at once. Each gets its own isolation boundary and network, with no shared state or collisions.
Bring your own provider and image, or use the built-in Claude, Codex, and Pi providers.
Works with macOS containers, Firecracker, or Docker, driven by stdlib Python only.
Run an agent as a developer today and it inherits everything that developer can reach: source, secrets, production included. That's the real blocker to running agents at work, not a leaked key. A bot-bottle manifest scopes a bottle to exactly the local files and routes its task needs instead of the developer's whole session. It's the same access-control paradigm teams already use for human collaborators, just applied to an agent.
Everything on this page is Apache-2.0 and stays that way — the sandbox, egress allowlists, credential shielding, and the manifest are the open core, not a trial. What we're building for teams is the layer above a single machine: centralized policy, audit trails, and role-based access across a fleet of bottles, plus an optional managed runner for teams that would rather not run the infrastructure themselves.