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
---
name: implementer
author:
name: implementer-bot
email: implementer@example.com # sets the agent's git author identity
forge-accounts:
project-gitea: # a named forge this agent can call
url: https://git.example.com/api/v1
auth:
type: token
token_secret: BOT_BOTTLE_FORGE_TOKEN # host env var — never seen by the agent
---
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:
repos:
project:
url: ssh://git@git.example.com/acme/project.git
forge: project-gitea # use the agent's forge account for API calls
egress:
routes:
# 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. The agent's identity signs its
commits; git-gate carries pushes to the project repo, and its forge
account reaches the Gitea API through the proxy — the bottle never holds
the token.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.