didericis
6b91506706
The previous diagram showed three parallel egress lanes — agent ↔ pipelock, agent ↔ git-gate, agent ↔ cred-proxy — each going off-box independently. That was true of an earlier shape but is now wrong on two counts: 1. cred-proxy's outbound HTTPS routes through pipelock (set when the SSRF / CA-trust wiring landed). All cred-proxy upstream bytes pass pipelock's allowlist + body scanner. 2. git-gate's SSH push/fetch is direct out the egress network and has never gone through pipelock — pipelock is HTTP-only. Reflect both: the diagram now collapses to one HTTP/HTTPS chokepoint (pipelock) that the agent and cred-proxy share, plus a separate SSH lane for git-gate. Prose paragraph above the diagram updated to call out the "everything except SSH" framing explicitly. Verified against the current code: HTTPS_PROXY=pipelock set on the agent in launch.py and on cred-proxy in DockerCredProxy.start; git-gate's create-args carry no proxy env vars.
343 lines
17 KiB
Markdown
343 lines
17 KiB
Markdown
<p align="center">
|
|
<img src="docs/logo.svg" alt="claude-bottle logo" width="140">
|
|
</p>
|
|
|
|
# claude-bottle
|
|
|
|
[](https://gitea.dideric.is/didericis/claude-bottle/actions?workflow=test.yml)
|
|
|
|
Run multiple Claude Code agents on your own machine, each scoped to its own secrets, skills, and egress allowlist.
|
|
|
|
|
|
|
|
Four prompts to the agent inside a real bottle:
|
|
claude replies to `hello there` — proof api.anthropic.com routes
|
|
through pipelock's bumped TLS end-to-end;
|
|
asked to GET a non-allowlisted host, the agent's curl gets 403 back
|
|
from pipelock;
|
|
asked to POST a credential-shaped body to an allowlisted host, the
|
|
same 403 — pipelock's DLP body scanner caught it;
|
|
asked to commit and push an AKIA-shaped key, git-gate's gitleaks
|
|
pre-receive hook rejects the ref.
|
|
Run it yourself with `bash scripts/demo.sh`.
|
|
|
|
## Why "claude-bottle"?
|
|
|
|
Each container is a bottle; Claude is the genie inside. The genie's
|
|
powers are exactly what the manifest grants it — a specific set of
|
|
skills, a specific set of secrets, and a specific set of hosts it can
|
|
reach — nothing more. You uncork one bottle per agent
|
|
(`./cli.py start <agent>`), many bottles run in parallel, and each is
|
|
scoped to its task. When the session ends the bottle is destroyed and
|
|
the genie does not persist.
|
|
|
|
## Goals
|
|
|
|
- Scope each agent to the minimum credentials and network egress its task actually needs
|
|
- Run multiple agents in parallel, isolated from each other
|
|
- Keep code, credentials, and agent activity on infrastructure I control — no third-party agent runtime
|
|
|
|
## Security model
|
|
|
|
Each agent runs in its own bottle: its own container, its own internal
|
|
Docker network, and its own pipelock sidecar. Bottles don't share
|
|
state, don't talk to each other, and only get the env vars, skills,
|
|
SSH identities, and egress hosts the manifest grants them — nothing
|
|
more. Any one agent only has the access it needs to do its job.
|
|
|
|
The bottle limits both what an agent can see and where it can send
|
|
it. Each bottle gets only the secrets and SSH identities the manifest
|
|
grants it — a Gitea token but not a GitHub token, a deploy key but
|
|
not a personal SSH key — so even a compromised or misbehaving agent
|
|
only handles credentials it was already trusted with for its job.
|
|
Egress flows through pipelock, which constrains where those
|
|
credentials can travel: an agent with a Gitea token can reach
|
|
`gitea.dideric.is`, not arbitrary attacker-controlled hosts. The same
|
|
constraint blocks DNS-over-HTTPS as an exfil channel — a DoH resolver
|
|
like `cloudflare-dns.com` would have to be on the allowlist for the
|
|
agent to reach it at all. The container itself adds a layer between
|
|
the agent and the host, but the v1 design leans more on secret
|
|
minimization and egress allowlisting than on the container as a
|
|
hardened boundary. On Linux hosts where [gVisor](https://gvisor.dev/)
|
|
is registered with Docker, claude-bottle auto-detects it and launches
|
|
every bottle under `runsc` for a userspace syscall barrier — no
|
|
manifest configuration required. The broader v2 discussion lives in
|
|
`docs/research/stronger-isolation-alternatives.md`.
|
|
|
|
The egress proxy and OAuth-token handling below are the load-bearing
|
|
pieces of v1.
|
|
|
|
## Architecture
|
|
|
|
A bottle is the agent container plus up to three per-protocol egress
|
|
sidecars on a per-agent Docker `--internal` network. The agent has no
|
|
default route off-box. All HTTP and HTTPS egress — from the agent
|
|
*and* from cred-proxy when it dials an upstream — funnels through
|
|
pipelock, where the egress allowlist, TLS interception, and
|
|
request-body DLP scanner enforce the manifest before any byte leaves
|
|
the host. The only egress that doesn't traverse pipelock is git-gate's
|
|
SSH push/fetch to `bottle.git` upstreams — pipelock can't proxy SSH,
|
|
so git-gate is its own L4-style egress path with gitleaks doing the
|
|
pre-receive scan.
|
|
|
|
```
|
|
host ( ./cli.py )
|
|
│
|
|
starts │ stops
|
|
▼
|
|
┌─────────────────────────── bottle ──────────────────────────────────┐
|
|
│ │
|
|
│ ┌──────────────────┐ │
|
|
│ │ agent image │ HTTPS_PROXY │
|
|
│ │ (claude-code, │ ────────────────────────┐ │
|
|
│ │ built locally) │ │ │
|
|
│ │ │ plain HTTP │ │
|
|
│ │ skills, env, │ (token injection) ┌────▼─────────┐ │
|
|
│ │ ~/.gitconfig, │ ──────────────────►│ cred-proxy │ │
|
|
│ │ ~/.npmrc, tea │ │ (strips/inj │ │
|
|
│ │ │ │ Authoriz.) │ │
|
|
│ │ environ: URLs │ └─────┬────────┘ │
|
|
│ │ only, no real │ HTTPS_PROXY │ │
|
|
│ │ tokens │ ▼ │
|
|
│ │ │ ┌────────────────┐ │ HTTPS to
|
|
│ │ │ │ pipelock image │──────────┼──► allowlisted
|
|
│ │ │ │ (TLS bump, DLP │ │ hosts (incl.
|
|
│ │ │ │ body scan, │ │ cred-proxy
|
|
│ │ │ │ allowlist) │ │ upstreams)
|
|
│ │ │ └────────────────┘ │
|
|
│ │ │ │
|
|
│ │ │ git:// ┌────────────────┐ │ SSH push/fetch
|
|
│ │ │ ────────────────►│ git-gate image │──────────┼──► to bottle.git
|
|
│ │ │ │ (gitleaks + │ │ upstreams
|
|
│ └──────────────────┘ │ git daemon) │ │ (direct — not
|
|
│ └────────────────┘ │ via pipelock)
|
|
│ │
|
|
│ agent on internal network (no default route); pipelock, │
|
|
│ cred-proxy, and git-gate straddle internal + egress networks. │
|
|
│ pipelock is the single HTTP/HTTPS chokepoint — cred-proxy's │
|
|
│ outbound traverses it too. git-gate's SSH egress is direct │
|
|
│ because pipelock is HTTP-only. │
|
|
└─────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
- **agent image** — built from the repo `Dockerfile` (`node:22-slim`
|
|
base) on first run; runs `claude` with the manifest-granted skills,
|
|
env vars, and `~/.gitconfig` (the latter for the git-gate's
|
|
`insteadOf` rules when `bottle.git` is set).
|
|
- **pipelock image** — per-agent sidecar. Terminates the agent's
|
|
outbound HTTP/HTTPS, enforces the resolved allowlist, runs DLP
|
|
scanning. Design in `docs/prds/0001-per-agent-egress-proxy-via-pipelock.md`
|
|
and `docs/prds/0006-pipelock-tls-interception.md`.
|
|
- **git-gate image** — per-agent sidecar built on `zricethezav/gitleaks`
|
|
(alpine + gitleaks + git-daemon + openssh-client). Runs
|
|
`git daemon` over `git://` as a bidirectional mirror of each
|
|
declared upstream. A pre-receive hook gitleaks-scans incoming
|
|
refs and forwards clean refs to the real upstream over SSH; an
|
|
access-hook runs `git fetch origin --prune` against the upstream
|
|
before every upload-pack so an agent fetch returns whatever the
|
|
upstream has *now* (fail-closed if unreachable). The agent's
|
|
`~/.gitconfig` rewrites the real URL to the gate via `insteadOf`,
|
|
so push, fetch, clone, and pull all route through. The agent
|
|
never sees the upstream credential. If the upstream's hostname
|
|
isn't resolvable from the gate container (e.g. a Tailscale-only
|
|
host whose public DNS points elsewhere), pin its IP via
|
|
`ExtraHosts: { "<hostname>": "<ip>" }` on the `bottle.git` entry —
|
|
the gate's `/etc/hosts` gets the override while the agent's
|
|
`insteadOf` rewrite still keys off the original hostname. Brought
|
|
up only when `bottle.git` has entries. Design in
|
|
`docs/prds/0008-git-gate.md`.
|
|
- **cred-proxy image** — per-bottle sidecar (`python:3.13-alpine`
|
|
base, stdlib-only) that holds API tokens declared in
|
|
`bottle.cred_proxy.routes`. Each route names a `path`,
|
|
`upstream`, `auth_scheme`, and `token_ref` (host env var); the
|
|
agent dials `http://cred-proxy:9099<path>...` over plain HTTP
|
|
and the proxy strips any inbound `Authorization`, injects
|
|
`<auth_scheme> <token>` using the value held only in its own
|
|
container's environ, and forwards to the real upstream over
|
|
HTTPS. SSE responses stream back unbuffered. The cred-proxy's
|
|
outbound HTTPS routes through pipelock (it trusts pipelock's
|
|
per-bottle CA), so pipelock's egress allowlist + body scanner
|
|
apply to cred-proxy traffic the same way they apply to direct
|
|
agent traffic. Smart-HTTP push paths (`/git-receive-pack`,
|
|
`/info/refs?service=git-receive-pack`) are refused at the
|
|
proxy — push must go through `bottle.git` / git-gate where
|
|
gitleaks runs. Optional per-route `role` tags drive agent-side
|
|
rewrites: `anthropic-base-url`, `npm-registry`, `git-insteadof`,
|
|
`tea-login`. The agent's `printenv` shows only proxy URLs —
|
|
none of the real token values. Design in
|
|
`docs/prds/0010-cred-proxy.md`.
|
|
|
|
When the agent exits, `cli.py` tears down every sidecar that was
|
|
brought up and the two networks; nothing about a bottle persists
|
|
between runs.
|
|
|
|
## Quickstart
|
|
|
|
Requires Docker on the host and a long-lived Claude Code OAuth token in
|
|
your shell env.
|
|
|
|
```sh
|
|
./cli.py start <agent> # builds the image on first run, drops you into claude
|
|
```
|
|
|
|
The container is removed automatically when the session ends. If the script
|
|
is killed with SIGKILL the exit trap won't fire and the container may be
|
|
left running; remove it with `docker rm -f <container-name>`.
|
|
|
|
## Manifest
|
|
|
|
Agents and the bottles they run in are declared in `claude-bottle.json`
|
|
in your project root or `$HOME` (both files merge if present, with
|
|
project entries overriding home entries on key conflict).
|
|
|
|
```jsonc
|
|
{
|
|
"bottles": {
|
|
"gitea-dev": {
|
|
"env": {
|
|
"GITEA_TOKEN": "?paste your Gitea API token",
|
|
"GITHUB_TOKEN": "${GH_PAT}",
|
|
"GIT_AUTHOR_NAME": "didericis"
|
|
},
|
|
|
|
"git": [
|
|
{
|
|
"Name": "claude-bottle",
|
|
"Upstream": "ssh://git@gitea.dideric.is:30009/didericis/claude-bottle.git",
|
|
"IdentityFile": "/Users/didericis/.ssh/id_ed25519_gitea",
|
|
"KnownHostKey": "ssh-ed25519 AAAA..."
|
|
}
|
|
],
|
|
|
|
// Routes declared here are held by a per-bottle cred-proxy
|
|
// sidecar, not the agent. Each route names a path the agent
|
|
// dials, the upstream the proxy forwards to, an auth_scheme,
|
|
// and a token_ref (host env var). The value goes into the
|
|
// sidecar's environ via `docker create -e`, never touches
|
|
// argv or disk. Optional `role` tags drive agent-side
|
|
// rewrites: `anthropic-base-url` (sets ANTHROPIC_BASE_URL),
|
|
// `npm-registry` (writes ~/.npmrc), `git-insteadof` (writes
|
|
// ~/.gitconfig), `tea-login` (writes ~/.config/tea/config.yml).
|
|
// See `docs/prds/0010-cred-proxy.md`.
|
|
"cred_proxy": {
|
|
"routes": [
|
|
{ "path": "/anthropic/", "upstream": "https://api.anthropic.com",
|
|
"auth_scheme": "Bearer", "token_ref": "CLAUDE_BOTTLE_OAUTH_TOKEN",
|
|
"role": "anthropic-base-url" },
|
|
{ "path": "/gh-api/", "upstream": "https://api.github.com",
|
|
"auth_scheme": "Bearer", "token_ref": "GITHUB_PAT" },
|
|
{ "path": "/gh-git/", "upstream": "https://github.com",
|
|
"auth_scheme": "Bearer", "token_ref": "GITHUB_PAT",
|
|
"role": "git-insteadof" },
|
|
{ "path": "/npm/", "upstream": "https://registry.npmjs.org",
|
|
"auth_scheme": "Bearer", "token_ref": "NPM_TOKEN",
|
|
"role": "npm-registry" }
|
|
]
|
|
},
|
|
|
|
// Egress is forced through a per-agent
|
|
// [pipelock](https://github.com/luckyPipewrench/pipelock) sidecar
|
|
// on a Docker `--internal` network — without the proxy the agent
|
|
// has no route off-box. The effective allowlist is the union of
|
|
// baked-in defaults (api.anthropic.com, claude.ai, ...) and the
|
|
// hostnames listed here. Pipelock also runs DLP scanning and
|
|
// detects URL-embedded high-entropy secrets. The resolved
|
|
// allowlist is shown in the y/N preflight before launch.
|
|
"egress": {
|
|
"allowlist": [
|
|
"github.com",
|
|
"registry.npmjs.org",
|
|
"pypi.org"
|
|
]
|
|
}
|
|
}
|
|
},
|
|
|
|
"agents": {
|
|
"gitea-helper": {
|
|
"bottle": "gitea-dev",
|
|
"skills": ["init-prd"],
|
|
"prompt": "You help maintain Gitea-hosted projects."
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Comments are illustrative; the file itself must be valid JSON. See
|
|
`claude-bottle.example.json` for a working starting point. Pipelock's
|
|
design lives in `docs/prds/0001-per-agent-egress-proxy-via-pipelock.md`
|
|
and the rationale in `docs/research/pipelock-assessment.md`.
|
|
|
|
## Auth: OAuth token, not API key
|
|
|
|
claude-bottle authenticates `claude` inside the container with the same
|
|
Pro/Max subscription you already use on the host, via a long-lived OAuth
|
|
token. No `ANTHROPIC_API_KEY` is needed.
|
|
|
|
**Why a token instead of mounting `~/.claude.json`:** on macOS, Claude
|
|
Code stores OAuth credentials in the encrypted Keychain, not in
|
|
`~/.claude.json`. Mounting that file into a Linux container does not
|
|
carry the credentials with it. Linux hosts keep credentials in
|
|
`~/.claude/.credentials.json`, but to keep the launcher portable
|
|
claude-bottle uses the env-var path on every host.
|
|
|
|
**One-time setup on the host:**
|
|
|
|
```sh
|
|
claude setup-token # browser login, prints a ~1-year OAuth token
|
|
```
|
|
|
|
Stash the token in your shell env (e.g. `~/.zshrc` or a secret manager)
|
|
as `CLAUDE_BOTTLE_OAUTH_TOKEN`:
|
|
|
|
```sh
|
|
export CLAUDE_BOTTLE_OAUTH_TOKEN="<token>"
|
|
```
|
|
|
|
The bottle reaches the Anthropic API only through the cred-proxy
|
|
sidecar. To let `claude` authenticate, declare a route in
|
|
`bottle.cred_proxy.routes` with `role: "anthropic-base-url"` and
|
|
`token_ref: "CLAUDE_BOTTLE_OAUTH_TOKEN"`:
|
|
|
|
```jsonc
|
|
{
|
|
"path": "/anthropic/",
|
|
"upstream": "https://api.anthropic.com",
|
|
"auth_scheme": "Bearer",
|
|
"token_ref": "CLAUDE_BOTTLE_OAUTH_TOKEN",
|
|
"role": "anthropic-base-url"
|
|
}
|
|
```
|
|
|
|
At launch, `cli.py` reads `CLAUDE_BOTTLE_OAUTH_TOKEN` from the host
|
|
env and forwards it into the cred-proxy container's environ — never
|
|
into the agent's. The agent receives `ANTHROPIC_BASE_URL` pointing at
|
|
`http://cred-proxy:9099/anthropic` and a non-secret placeholder for
|
|
`CLAUDE_CODE_OAUTH_TOKEN` (claude-code refuses to start without one;
|
|
the proxy strips and replaces the header on every request). `printenv`
|
|
inside the agent does not surface the real token, and the value is
|
|
never written to disk or placed on argv on the host.
|
|
|
|
A bottle without an `anthropic-base-url` route has no path to the
|
|
Anthropic API — there is no fallback that forwards the token directly
|
|
to the agent. Caveats: the token is bound to your subscription tier
|
|
(Pro/Max/Team/Enterprise), it does not work with `claude --bare`
|
|
(which only reads `ANTHROPIC_API_KEY`), and if it leaks, regenerate
|
|
via `claude setup-token` again. Reference:
|
|
<https://code.claude.com/docs/en/authentication>.
|
|
|
|
## Trademarks
|
|
|
|
claude-bottle is an independent project and is not affiliated with,
|
|
endorsed by, or sponsored by Anthropic, PBC. "Claude" and "Claude
|
|
Code" are trademarks of Anthropic, PBC; the project name uses
|
|
"claude" descriptively to indicate that the tool runs Claude Code
|
|
inside a sandbox.
|
|
|
|
## License
|
|
|
|
Copyright 2026 Eric Bauerfeld
|
|
|
|
Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE)
|
|
for the full text.
|