didericis/bot-bottle
1
0
Fork 0
Code Issues 5 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

refactor: convert project from bash to Python

Browse Source 
Replaces cli.sh + lib/*.sh with a claude_bottle/ Python package and a
cli.py entry point. No external dependencies — uses only Python's
stdlib (json, subprocess, getpass, tempfile, argparse, re, etc.).

- claude_bottle/{log,docker,manifest,env_resolve,network,pipelock,
  skills,ssh,cli}.py mirror the previous lib/*.sh modules.
- Tests converted to unittest under tests/test_*.py with a stdlib
  runner at tests/run_tests.py (unit | integration | path).
- .githooks/commit-msg ported to Python; same Conventional Commits rules.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit was merged in pull request #2.
This commit is contained in:
didericis
2026-05-08 15:26:58 +00:00
parent b94b6904ae
commit 399ed93dc8
47 changed files with 2706 additions and 3586 deletions
Download Patch File Download Diff File Expand all files Collapse all files
claude_bottle/__init__.py
+1
View File
@@ -0,0 +1 @@
"""claude-bottle: Python implementation of the agent container launcher."""
claude_bottle/cli.py
+758
View File
@@ -0,0 +1,758 @@
"""Main CLI dispatcher.
Commands: build, cleanup, edit, info, init, list, start
"""
from __future__ import annotations
import argparse
import json
import os
import re
import shutil
import subprocess
import sys
import tempfile
from pathlib import Path
from typing import Any
from . import docker as docker_mod
from . import network as network_mod
from . import pipelock
from . import skills as skills_mod
from . import ssh as ssh_mod
from .env_resolve import env_resolve
from .log import Die, die, info, warn
from .manifest import (
Manifest,
manifest_agent_bottle,
manifest_env_names,
manifest_prompt,
manifest_require_agent,
manifest_require_bottle,
manifest_resolve,
manifest_skills,
manifest_ssh,
)
PROG = "cli.py"
USER_CWD = os.getcwd()
REPO_DIR = str(Path(__file__).resolve().parent.parent)
# ---------------------------------------------------------------------------
# Subcommands
# ---------------------------------------------------------------------------
def cmd_build(_argv: list[str]) -> int:
docker_mod.require_docker()
image = os.environ.get("CLAUDE_BOTTLE_IMAGE", "claude-bottle:latest")
docker_mod.build_image(image, REPO_DIR)
return 0
def cmd_info(argv: list[str]) -> int:
parser = argparse.ArgumentParser(prog=f"{PROG} info", add_help=True)
parser.add_argument("name", help="agent name defined in claude-bottle.json")
args = parser.parse_args(argv)
manifest = manifest_resolve(USER_CWD)
manifest_require_agent(manifest, args.name)
env_names = manifest_env_names(manifest, args.name)
skill_names = manifest_skills(manifest, args.name)
prompt_content = manifest_prompt(manifest, args.name)
prompt_first_line = prompt_content.splitlines()[0] if prompt_content else ""
bottle_name = manifest_agent_bottle(manifest, args.name)
ssh_entries = manifest_ssh(manifest, args.name)
print()
info(f"agent : {args.name}")
info(f"env (names only): {', '.join(env_names) if env_names else '(none)'}")
info(f"skills : {' '.join(skill_names) if skill_names else '(none)'}")
info(
f"prompt : {len(prompt_content)} chars; "
f"first line: {prompt_first_line or '(empty)'}"
)
if bottle_name:
info(f"bottle : {bottle_name}")
if ssh_entries:
for e in ssh_entries:
info(
f" ssh host : {e.get('Host')} "
f"(Hostname={e.get('Hostname')}, User={e.get('User')}, "
f"Port={e.get('Port')}, IdentityFile={e.get('IdentityFile')})"
)
if e.get("KnownHostKey"):
info(f" KnownHostKey: {e['KnownHostKey']}")
else:
info(" ssh hosts : (none)")
else:
info("bottle : (none)")
print()
return 0
def cmd_list(argv: list[str]) -> int:
parser = argparse.ArgumentParser(prog=f"{PROG} list", add_help=True)
parser.add_argument("scope", choices=["available", "active"])
args = parser.parse_args(argv)
if args.scope == "available":
manifest = manifest_resolve(USER_CWD)
for name in (manifest.get("agents") or {}).keys():
print(name)
return 0
docker_mod.require_docker()
result = subprocess.run(
[
"docker", "ps",
"--filter", "name=^claude-bottle-",
"--format", "{{.Names}}\t{{.Status}}",
],
capture_output=True,
text=True,
)
containers = (result.stdout or "").strip()
if not containers:
info("no active claude-bottle containers")
return 0
print()
for line in containers.splitlines():
name, _, status = line.partition("\t")
info(f"container: {name} status: {status}")
print()
return 0
def cmd_cleanup(_argv: list[str]) -> int:
docker_mod.require_docker()
result = subprocess.run(
["docker", "ps", "--filter", "name=^claude-bottle-", "--format", "{{.Names}}"],
capture_output=True,
text=True,
)
containers = (result.stdout or "").strip()
if not containers:
info("no active claude-bottle containers")
return 0
print(file=sys.stderr)
for name in containers.splitlines():
info(f"found: {name}")
print(file=sys.stderr)
sys.stderr.write("claude-bottle: remove all of the above? [y/N] ")
sys.stderr.flush()
reply = _read_tty_line()
if reply not in ("y", "Y", "yes", "YES"):
info("aborted")
return 0
for name in containers.splitlines():
info(f"removing {name}")
subprocess.run(
["docker", "rm", "-f", name],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
)
info("done")
return 0
def cmd_start(argv: list[str]) -> int:
parser = argparse.ArgumentParser(prog=f"{PROG} start", add_help=True)
parser.add_argument("--dry-run", action="store_true")
parser.add_argument("--cwd", action="store_true", help="copy host cwd into a derived image")
parser.add_argument("--remote-control", action="store_true")
parser.add_argument("name", help="agent name defined in claude-bottle.json")
args = parser.parse_args(argv)
dry_run = args.dry_run or os.environ.get("CLAUDE_BOTTLE_DRY_RUN") == "1"
name = args.name
slug = docker_mod.slugify(name)
image = os.environ.get("CLAUDE_BOTTLE_IMAGE", "claude-bottle:latest")
default_container = f"claude-bottle-{slug}"
pinned_container = os.environ.get("CLAUDE_BOTTLE_CONTAINER", "")
runtime_image = image
derived_image = ""
if args.cwd:
derived_image = os.environ.get("CLAUDE_BOTTLE_DERIVED_IMAGE", f"claude-bottle:cwd-{slug}")
runtime_image = derived_image
docker_mod.require_docker()
manifest = manifest_resolve(USER_CWD)
manifest_require_agent(manifest, name)
container = pinned_container or default_container
suffix = 2
if pinned_container:
if docker_mod.container_exists(container):
die(
f"container '{container}' already exists "
f"(pinned via CLAUDE_BOTTLE_CONTAINER). "
f"Remove it with 'docker rm -f {container}' or unset the override."
)
else:
while docker_mod.container_exists(container):
container = f"{default_container}-{suffix}"
suffix += 1
if suffix > 100:
die(
f"could not find a free container name after "
f"{default_container}-99; clean up old containers with "
f"'docker rm -f <name>'"
)
# --- Plan resolution (host-only, no container yet) ---
env_names = manifest_env_names(manifest, name)
# CLAUDE_BOTTLE_OAUTH_TOKEN → CLAUDE_CODE_OAUTH_TOKEN forwarding.
# Host-side token is always forwarded so every container can authenticate.
forward_oauth_token = bool(os.environ.get("CLAUDE_BOTTLE_OAUTH_TOKEN"))
display_env_names = list(env_names)
if forward_oauth_token:
display_env_names.append("CLAUDE_CODE_OAUTH_TOKEN")
skill_names = manifest_skills(manifest, name)
if skill_names:
skills_mod.skills_validate_all(skill_names)
bottle_name = manifest_agent_bottle(manifest, name)
if not bottle_name:
die(
f"agent '{name}' has no 'bottle' field. "
f"Add a bottle association to this agent in claude-bottle.json."
)
manifest_require_bottle(manifest, bottle_name)
ssh_entries = manifest_ssh(manifest, name)
if ssh_entries:
ssh_mod.ssh_validate_entries(ssh_entries)
stage_dir = Path(tempfile.mkdtemp(prefix="claude-bottle-stage."))
env_file = stage_dir / "agent.env"
args_file = stage_dir / "docker-args"
prompt_file = stage_dir / "prompt.txt"
pipelock_yaml_filename = "pipelock.yaml"
pipelock_yaml = stage_dir / pipelock_yaml_filename
env_file.write_text("")
env_file.chmod(0o600)
args_file.write_text("")
prompt_file.write_text("")
prompt_file.chmod(0o600)
# cleanup state — populated as resources come up.
state: dict[str, str] = {
"container": "",
"pipelock": "",
"internal_network": "",
"egress_network": "",
}
def cleanup_all() -> None:
try:
if state["container"] and docker_mod.container_exists(state["container"]):
subprocess.run(
["docker", "rm", "-f", state["container"]],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
)
if state["pipelock"]:
pipelock.pipelock_stop(slug)
if state["internal_network"]:
network_mod.network_remove(state["internal_network"])
if state["egress_network"]:
network_mod.network_remove(state["egress_network"])
finally:
shutil.rmtree(stage_dir, ignore_errors=True)
try:
pipelock.pipelock_write_yaml(manifest, bottle_name, pipelock_yaml)
allowlist_summary = pipelock.pipelock_allowlist_summary(manifest, bottle_name)
env_resolve(manifest, name, env_file, args_file)
prompt_content = manifest_prompt(manifest, name)
prompt_file.write_text(prompt_content)
prompt_first_line = prompt_content.splitlines()[0] if prompt_content else ""
# --- Plan + confirm ---
print(file=sys.stderr)
info(f"agent : {name}")
info(f"image : {image}")
if derived_image:
info(f"cwd : {USER_CWD} -> /home/node/workspace (derived: {derived_image})")
info(f"container : {container}")
info(f"stage dir : {stage_dir}")
info(
"env (names only): "
+ (", ".join(display_env_names) if display_env_names else "(none)")
)
info("skills : " + (" ".join(skill_names) if skill_names else "(none)"))
info(f"bottle : {bottle_name}")
if ssh_entries:
ssh_names = ", ".join(e.get("Host", "") for e in ssh_entries)
info(f" ssh hosts : {ssh_names}")
else:
info(" ssh hosts : (none)")
info(f" egress : {allowlist_summary}")
info(
f"prompt : {len(prompt_content)} chars; "
f"first line: {prompt_first_line or '(empty)'}"
)
info("remote-control : " + ("enabled" if args.remote_control else "disabled"))
print(file=sys.stderr)
if dry_run:
info("dry-run requested; not starting container.")
cleanup_all()
return 0
sys.stderr.write("claude-bottle: launch this agent? [y/N] ")
sys.stderr.flush()
reply = _read_tty_line()
if reply not in ("y", "Y", "yes", "YES"):
info("aborted by user")
cleanup_all()
return 0
# --- Build & launch ---
docker_mod.build_image(image, REPO_DIR)
if derived_image:
docker_mod.build_image_with_cwd(derived_image, image, USER_CWD)
state["internal_network"] = network_mod.network_create_internal(slug)
state["egress_network"] = network_mod.network_create_egress(slug)
state["pipelock"] = pipelock.pipelock_start(
slug,
state["internal_network"],
state["egress_network"],
stage_dir,
pipelock_yaml_filename,
)
proxy_url = pipelock.pipelock_proxy_url(slug)
docker_args: list[str] = [
"--rm", "-d",
"--name", container,
"--network", state["internal_network"],
"-e", f"HTTPS_PROXY={proxy_url}",
"-e", f"HTTP_PROXY={proxy_url}",
"-e", "NO_PROXY=localhost,127.0.0.1",
]
if env_file.stat().st_size > 0:
docker_args.extend(["--env-file", str(env_file)])
# ARGS_FILE pairs (-e, NAME) line-by-line.
args_lines = args_file.read_text().splitlines()
i = 0
while i < len(args_lines):
flag = args_lines[i]
i += 1
if not flag:
continue
if i >= len(args_lines):
break
vname = args_lines[i]
i += 1
docker_args.extend([flag, vname])
if forward_oauth_token:
os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = os.environ["CLAUDE_BOTTLE_OAUTH_TOKEN"]
docker_args.extend(["-e", "CLAUDE_CODE_OAUTH_TOKEN"])
docker_args.extend([runtime_image, "sleep", "infinity"])
info(f"starting container {container} from {runtime_image}")
# Retry-on-name-conflict loop to mirror the bash version.
while True:
full_argv = ["docker", "run", *docker_args]
run_result = subprocess.run(full_argv, capture_output=True, text=True)
if run_result.returncode == 0:
state["container"] = container
break
err_text = run_result.stderr
if pinned_container or "is already in use" not in err_text:
sys.stderr.write(err_text + "\n")
die(f"docker run failed for container '{container}'")
if suffix > 100:
die(
f"could not find a free container name after "
f"{default_container}-99 retries; clean up old containers"
)
container = f"{default_container}-{suffix}"
suffix += 1
# Replace --name slot in docker_args.
name_idx = docker_args.index("--name") + 1
docker_args[name_idx] = container
info(f"name conflict; retrying as {container}")
container_prompt_path = (
os.environ.get("CLAUDE_BOTTLE_CONTAINER_HOME", "/home/node")
+ "/.claude-bottle-prompt.txt"
)
subprocess.run(
["docker", "cp", str(prompt_file), f"{container}:{container_prompt_path}"],
stdout=subprocess.DEVNULL,
check=True,
)
# `docker cp` preserves host UID; re-own/mode as root in the container
# so node can read its own mode-600 prompt regardless of host UID.
subprocess.run(
["docker", "exec", "-u", "0", container, "chown", "node:node", container_prompt_path],
stdout=subprocess.DEVNULL,
check=True,
)
subprocess.run(
["docker", "exec", "-u", "0", container, "chmod", "600", container_prompt_path],
stdout=subprocess.DEVNULL,
check=True,
)
if skill_names:
skills_mod.skills_copy_into(container, skill_names)
if ssh_entries:
proxy_host_port = pipelock.pipelock_proxy_host_port(slug)
ssh_mod.ssh_setup(container, stage_dir, proxy_host_port, ssh_entries)
if args.cwd and Path(USER_CWD, ".git").is_dir():
info(f"copying {USER_CWD}/.git -> {container}:/home/node/workspace/.git")
subprocess.run(
["docker", "cp", f"{USER_CWD}/.git", f"{container}:/home/node/workspace/.git"],
stdout=subprocess.DEVNULL,
check=True,
)
subprocess.run(
["docker", "exec", "-u", "0", container, "chown", "-R", "node:node", "/home/node/workspace/.git"],
stdout=subprocess.DEVNULL,
check=True,
)
info(
"attaching interactive claude session "
"(Ctrl-D or 'exit' to leave; container will be removed)"
)
claude_args = ["--dangerously-skip-permissions"]
if args.remote_control:
claude_args.append("--remote-control")
if prompt_content:
subprocess.run(
[
"docker", "exec", "-it", container, "claude",
*claude_args,
"--append-system-prompt-file", container_prompt_path,
]
)
else:
subprocess.run(
["docker", "exec", "-it", container, "claude", *claude_args]
)
info(f"session ended; container {container} will be removed")
return 0
finally:
cleanup_all()
# ---------------------------------------------------------------------------
# init / edit
# ---------------------------------------------------------------------------
def cmd_init(argv: list[str]) -> int:
parser = argparse.ArgumentParser(prog=f"{PROG} init", add_help=True)
parser.add_argument("scope", choices=["user", "project"])
args = parser.parse_args(argv)
if args.scope == "user":
target_file = Path(os.environ["HOME"]) / "claude-bottle.json"
else:
target_file = Path(USER_CWD) / "claude-bottle.json"
print(file=sys.stderr)
info(f"claude-bottle init — adding a new agent to {target_file}")
print(file=sys.stderr)
# Agent name
agent_name = ""
while not agent_name:
sys.stderr.write("Agent name: ")
sys.stderr.flush()
agent_name = _read_tty_line().replace(" ", "-")
if not agent_name:
warn("agent name cannot be empty")
if not re.match(r"^[a-z0-9][a-z0-9-]*$", agent_name):
warn(
f"agent name '{agent_name}' contains non-slug characters; "
f"it will still work but may cause container naming issues"
)
existing: dict[str, Any] = {}
if target_file.is_file():
try:
existing = json.loads(target_file.read_text())
except json.JSONDecodeError:
die(f"{target_file} exists but is not valid JSON; fix or remove it first")
if agent_name in (existing.get("agents") or {}):
sys.stderr.write(
f'claude-bottle: agent "{agent_name}" already exists in {target_file}. Overwrite? [y/N] '
)
sys.stderr.flush()
ow = _read_tty_line()
if ow not in ("y", "Y", "yes", "YES"):
info("aborted")
return 0
# Skills
print(file=sys.stderr)
sys.stderr.write("Skills (space or comma separated, or Enter for none): ")
sys.stderr.flush()
skills_input = _read_tty_line()
skill_list: list[str] = []
if skills_input:
cleaned = skills_input.replace(",", " ")
skill_list = [s for s in cleaned.split() if s]
# Prompt
print(file=sys.stderr)
info("System prompt — enter text, then a lone '.' on its own line to finish (just '.' to leave empty):")
prompt_lines: list[str] = []
while True:
line = _read_tty_line()
if line == ".":
break
prompt_lines.append(line)
prompt_content = "\n".join(prompt_lines)
# Bottle association
print(file=sys.stderr)
sys.stderr.write("Associate this agent with a bottle? [y/N] ")
sys.stderr.flush()
bottle_yn = _read_tty_line()
bottle_name = ""
bottle_env: dict[str, str] = {}
bottle_ssh: list[dict[str, Any]] = []
bottle_exists_already = False
if bottle_yn in ("y", "Y", "yes", "YES"):
while not bottle_name:
sys.stderr.write(" Bottle name: ")
sys.stderr.flush()
bottle_name = _read_tty_line().replace(" ", "-")
if not bottle_name:
warn("bottle name cannot be empty")
if bottle_name in (existing.get("bottles") or {}):
bottle_exists_already = True
info(f"Bottle '{bottle_name}' already exists in {target_file}; agent will reference it.")
else:
info(f"Creating new bottle '{bottle_name}'.")
bottle_env = _prompt_for_env_vars()
sys.stderr.write(" Add SSH host entries to this bottle? [y/N] ")
sys.stderr.flush()
ssh_yn = _read_tty_line()
if ssh_yn in ("y", "Y", "yes", "YES"):
bottle_ssh = _prompt_for_ssh_entries()
# Build agent JSON
agent_def: dict[str, Any] = {"skills": skill_list, "prompt": prompt_content}
if bottle_name:
agent_def["bottle"] = bottle_name
merged: dict[str, Any] = {
"bottles": dict(existing.get("bottles") or {}),
"agents": dict(existing.get("agents") or {}),
}
if bottle_name and not bottle_exists_already:
merged["bottles"][bottle_name] = {"env": bottle_env, "ssh": bottle_ssh}
merged["agents"][agent_name] = agent_def
target_file.write_text(json.dumps(merged, indent=2) + "\n")
info(f"Agent '{agent_name}' written to {target_file}.")
info(f"Run '{PROG} info {agent_name}' to verify.")
print(file=sys.stderr)
return 0
def _prompt_for_env_vars() -> dict[str, str]:
print(file=sys.stderr)
info("Env vars — enter each var name then its mode. Press Enter with no name to finish.")
info(" Modes: secret (prompt at runtime) | interpolated (read from host env) | literal (hardcoded value)")
out: dict[str, str] = {}
while True:
print(file=sys.stderr)
sys.stderr.write(" Var name (or Enter to finish): ")
sys.stderr.flush()
vname = _read_tty_line()
if not vname:
break
sys.stderr.write(" Mode [secret/interpolated/literal] (default: secret): ")
sys.stderr.flush()
vmode = _read_tty_line() or "secret"
if vmode == "secret":
sys.stderr.write(f' Prompt message shown to user (default: "enter {vname}"): ')
sys.stderr.flush()
smsg = _read_tty_line()
value = f"?{smsg}" if smsg else "?"
elif vmode == "interpolated":
sys.stderr.write(f" Host env var to read from (default: {vname}): ")
sys.stderr.flush()
hvar = _read_tty_line() or vname
value = "${" + hvar + "}"
elif vmode == "literal":
sys.stderr.write(" Value: ")
sys.stderr.flush()
value = _read_tty_line()
else:
warn(f"unknown mode '{vmode}'; using secret")
value = "?"
out[vname] = value
return out
def _prompt_for_ssh_entries() -> list[dict[str, Any]]:
out: list[dict[str, Any]] = []
while True:
print(file=sys.stderr)
sys.stderr.write(" SSH Host alias (or Enter to finish): ")
sys.stderr.flush()
shost = _read_tty_line()
if not shost:
break
sys.stderr.write(" Hostname (actual hostname or IP): ")
sys.stderr.flush()
shostname = _read_tty_line()
sys.stderr.write(" User: ")
sys.stderr.flush()
suser = _read_tty_line()
sys.stderr.write(" Port (default: 22): ")
sys.stderr.flush()
sport_raw = _read_tty_line() or "22"
if not sport_raw.isdigit():
warn("port must be a number; defaulting to 22")
sport_raw = "22"
sport = int(sport_raw)
sys.stderr.write(" IdentityFile (path to private key on host): ")
sys.stderr.flush()
sidentity = _read_tty_line()
sys.stderr.write(" KnownHostKey (optional, Enter to skip): ")
sys.stderr.flush()
skhk = _read_tty_line()
entry: dict[str, Any] = {
"Host": shost,
"Hostname": shostname,
"User": suser,
"Port": sport,
"IdentityFile": sidentity,
}
if skhk:
entry["KnownHostKey"] = skhk
out.append(entry)
return out
def cmd_edit(argv: list[str]) -> int:
parser = argparse.ArgumentParser(prog=f"{PROG} edit", add_help=True)
parser.add_argument("scope", choices=["user", "project"])
parser.add_argument("name")
args = parser.parse_args(argv)
if args.scope == "user":
target_file = Path(os.environ["HOME"]) / "claude-bottle.json"
else:
target_file = Path(USER_CWD) / "claude-bottle.json"
if not target_file.is_file():
die(f"{target_file} does not exist")
try:
doc = json.loads(target_file.read_text())
except json.JSONDecodeError:
die(f"{target_file} is not valid JSON")
if args.name not in (doc.get("agents") or {}):
die(f"agent '{args.name}' not found in {target_file}")
line = 1
text = target_file.read_text().splitlines()
needle = f'"{args.name}"'
for idx, l in enumerate(text, start=1):
if needle in l:
line = idx
break
os.execvp("vim", ["vim", f"+{line}", str(target_file)])
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def _read_tty_line() -> str:
"""Mirror `IFS= read -r REPLY </dev/tty`. Falls back to stdin."""
try:
with open("/dev/tty", "r") as tty:
return tty.readline().rstrip("\n")
except OSError:
return sys.stdin.readline().rstrip("\n")
# ---------------------------------------------------------------------------
# Dispatch
# ---------------------------------------------------------------------------
COMMANDS = {
"build": cmd_build,
"cleanup": cmd_cleanup,
"edit": cmd_edit,
"info": cmd_info,
"init": cmd_init,
"list": cmd_list,
"start": cmd_start,
}
def usage() -> None:
sys.stderr.write(f"usage: {PROG} <command> [args...]\n\n")
sys.stderr.write("Commands:\n")
sys.stderr.write(" build build (or rebuild) the claude-bottle Docker image\n")
sys.stderr.write(" cleanup stop and remove all active claude-bottle containers\n")
sys.stderr.write(" edit open an agent in vim for editing\n")
sys.stderr.write(" info print env, skills, and prompt details for a named agent\n")
sys.stderr.write(" init interactively create a new agent and add it to claude-bottle.json\n")
sys.stderr.write(" list list available agents or active containers\n")
sys.stderr.write(" start boot a container for a named agent and attach an interactive session\n\n")
sys.stderr.write(f"Run '{PROG} <command> --help' for command-specific usage.\n")
def main(argv: list[str] | None = None) -> int:
if argv is None:
argv = sys.argv[1:]
if not argv:
usage()
return 2
command = argv[0]
rest = argv[1:]
if command in ("-h", "--help"):
usage()
return 0
handler = COMMANDS.get(command)
if handler is None:
usage()
die(f"unknown command: {command}")
try:
return handler(rest) or 0
except Die as e:
return e.code if isinstance(e.code, int) else 1
except KeyboardInterrupt:
return 130
if __name__ == "__main__":
sys.exit(main())
claude_bottle/docker.py
+95
View File
@@ -0,0 +1,95 @@
"""Docker helpers. Build/inspect primitives shared by the CLI."""
from __future__ import annotations
import re
import shutil
import subprocess
from typing import Iterable
from .log import die, info
def require_docker() -> None:
"""Fail with an install pointer if `docker` is not on PATH."""
if shutil.which("docker") is None:
info("Docker is required but was not found on PATH.")
info("macOS: install Docker Desktop https://docs.docker.com/desktop/install/mac-install/")
info("Linux: install Docker Engine https://docs.docker.com/engine/install/")
die("docker not found")
def image_exists(ref: str) -> bool:
return _silent_run(["docker", "image", "inspect", ref]) == 0
def container_exists(name: str) -> bool:
"""Returns True if a container (running or stopped) with the given
name exists. Uses `docker ps -a -q -f name=^<name>$` so substring
matches don't false-positive."""
result = subprocess.run(
["docker", "ps", "-a", "-q", "-f", f"name=^{name}$"],
capture_output=True,
text=True,
)
return bool(result.stdout.strip())
_SLUG_RE = re.compile(r"[^a-z0-9]+")
def slugify(name: str) -> str:
"""Lowercase, non-alnum runs → '-', trimmed. Dies on empty result."""
if not name:
die("slugify: missing name")
slug = _SLUG_RE.sub("-", name.lower()).strip("-")
if not slug:
die(f"name '{name}' produced an empty slug; use alphanumeric characters")
return slug
def build_image(ref: str, context: str) -> None:
"""Invokes `docker build` every call. Layer cache makes no-change
rebuilds cheap; running every time means Dockerfile edits land
without manual `docker rmi`."""
info(f"building image {ref} from {context} (layer cache keeps repeat builds fast)")
subprocess.run(["docker", "build", "-t", ref, context], check=True)
_TRUST_DIALOG_NODE_SCRIPT = (
'const fs=require("fs"),p=process.env.HOME+"/.claude.json",'
'c=JSON.parse(fs.readFileSync(p,"utf8"));'
'c.projects=c.projects||{};'
'c.projects[process.env.HOME+"/workspace"]={hasTrustDialogAccepted:true};'
'fs.writeFileSync(p,JSON.stringify(c,null,2));'
)
def build_image_with_cwd(derived: str, base: str, cwd: str) -> None:
"""Build a thin derived image that copies <cwd> into
/home/node/workspace and adds a trust-dialog entry for it."""
import os
if not os.path.isdir(cwd):
die(f"cwd not found at {cwd}")
info(f"building image {derived} from {base} with {cwd} -> /home/node/workspace")
dockerfile = (
f"FROM {base}\n"
f"COPY --chown=node:node . /home/node/workspace\n"
f"RUN node -e '{_TRUST_DIALOG_NODE_SCRIPT}'\n"
f"WORKDIR /home/node/workspace\n"
)
subprocess.run(
["docker", "build", "-t", derived, "-f", "-", cwd],
input=dockerfile,
text=True,
check=True,
)
def _silent_run(cmd: Iterable[str]) -> int:
return subprocess.run(
list(cmd),
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
).returncode
claude_bottle/env_resolve.py
+140
View File
@@ -0,0 +1,140 @@
"""Env resolver. Walks the env entries for one agent and produces:
1. The list of `docker run` arg fragments needed to forward each var.
Both `secret` and `interpolated` entries become `-e NAME` (no
`=value`) so Docker inherits the value from this process env
without rendering it on argv or persisting it to disk.
Only `literal` entries are written to a host-disk env-file.
2. The export side-effect of populating this process's env with
secret values prompted from the user, and with interpolated
values copied from the matching host var, so `-e NAME` actually
has something to inherit.
Each env entry is a string. Mode is selected by sentinel prefix:
"?" → secret (prompt at runtime). Bare "?" uses default prompt;
"?<message>" uses <message> as the prompt body.
"${HOST_VAR}" → interpolated from $HOST_VAR in the host process env
any other str → literal (the string is the value verbatim)
Critical rules:
- NEVER echo, log, or interpolate the value of a secret or
interpolated env var. Both are treated as potentially sensitive:
nothing about their value (other than presence) ever lands on
disk, in a log line, or on argv.
- The env-file written for literals lives under mktemp -d with mode
600, removed by the caller's cleanup.
- Errors mention only the variable NAME, never any portion of the value.
"""
from __future__ import annotations
import getpass
import os
import re
import sys
from pathlib import Path
from .log import die
from .manifest import Manifest, manifest_env_entry, manifest_env_names
_INTERPOLATED_RE = re.compile(r"^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$")
def env_entry_kind(raw: str) -> str:
"""Returns 'secret', 'interpolated', or 'literal'."""
if raw.startswith("?"):
return "secret"
if _INTERPOLATED_RE.match(raw):
return "interpolated"
return "literal"
def env_entry_secret_prompt(raw: str) -> str:
"""For a secret entry, the prompt body (after the leading '?').
Empty for bare '?', meaning use default."""
if raw.startswith("?"):
return raw[1:]
return ""
def env_entry_interpolated_from(raw: str) -> str:
"""For an interpolated entry, the host var name between '${' and '}'."""
m = _INTERPOLATED_RE.match(raw)
if not m:
return ""
return m.group(1)
def _read_secret_silent(name: str, prompt_body: str) -> str:
"""Read a secret value from the controlling tty without echoing.
The "(input hidden): " tail is always appended; manifest authors
write only the message text."""
if not (sys.stdin.isatty() or sys.stderr.isatty()):
# Fall back to /dev/tty so this still works when stdin is a pipe.
try:
tty = open("/dev/tty", "r+")
except OSError:
die(
f"cannot prompt for secret '{name}': no tty available. "
f"Run from an interactive shell."
)
prompt = (
f"{prompt_body} (input hidden): "
if prompt_body
else f"claude-bottle: secret value for {name} (input hidden): "
)
value = getpass.getpass(prompt, stream=tty)
tty.close()
else:
prompt = (
f"{prompt_body} (input hidden): "
if prompt_body
else f"claude-bottle: secret value for {name} (input hidden): "
)
value = getpass.getpass(prompt)
if not value:
die(f"empty value provided for secret '{name}'. Re-run and supply a value.")
return value
def env_resolve(
manifest: Manifest,
agent: str,
env_file: Path,
out_args: Path,
) -> None:
"""Iterate the agent's env entries:
- secret: always prompt; export into this process; append `-e NAME` to out_args
- interpolated: copy host value; export under target name; append `-e NAME`
- literal: append `NAME=VALUE` to env_file
"""
for name in manifest_env_names(manifest, agent):
if not name:
continue
raw = manifest_env_entry(manifest, agent, name)
kind = env_entry_kind(raw)
if kind == "secret":
prompt_body = env_entry_secret_prompt(raw)
value = _read_secret_silent(name, prompt_body)
os.environ[name] = value
with out_args.open("a") as f:
f.write(f"-e\n{name}\n")
elif kind == "interpolated":
host_var = env_entry_interpolated_from(raw)
host_value = os.environ.get(host_var, "")
if not host_value:
die(
f"env entry {name} is interpolated from ${host_var}, "
f"but ${host_var} is unset or empty in the host environment."
)
os.environ[name] = host_value
with out_args.open("a") as f:
f.write(f"-e\n{name}\n")
else: # literal
if "\n" in raw:
die(
f"env entry {name} (literal) contains a newline; "
f"docker --env-file cannot represent multi-line values."
)
with env_file.open("a") as f:
f.write(f"{name}={raw}\n")
claude_bottle/log.py
+23
View File
@@ -0,0 +1,23 @@
"""Tiny logging wrappers. All output goes to stderr."""
from __future__ import annotations
import sys
def info(msg: str) -> None:
print(f"claude-bottle: {msg}", file=sys.stderr)
def warn(msg: str) -> None:
print(f"claude-bottle: warning: {msg}", file=sys.stderr)
class Die(SystemExit):
"""Raised by die() so callers (and tests) can distinguish a deliberate
fatal exit from an unrelated SystemExit."""
def die(msg: str) -> "Die":
print(f"claude-bottle: error: {msg}", file=sys.stderr)
raise Die(1)
claude_bottle/manifest.py
+195
View File
@@ -0,0 +1,195 @@
"""Manifest helpers. Read claude-bottle.json and pull the definition for a
named agent.
Schema (see CLAUDE.md "Intended design"):
{
"bottles": {
"<bottle-name>": {
"env": { "<NAME>": <env-entry>, ... },
"ssh": [ <ssh-entry>, ... ],
"egress": { "allowlist": [ "<hostname>", ... ] }
}
},
"agents": {
"<agent-name>": {
"skills": [ "<skill-name>", ... ],
"prompt": "<string>",
"bottle": "<bottle-name>"
}
}
}
Bottles group shared infrastructure (SSH keys, known hosts, egress allowlist)
that multiple agents can reference. Every agent must reference a bottle.
"""
from __future__ import annotations
import json
import os
from pathlib import Path
from typing import Any
from .log import die
Manifest = dict[str, Any]
def manifest_resolve(cwd: str) -> Manifest:
"""Look for claude-bottle.json in <cwd> and in $HOME, deep-merge
them (cwd entries override home entries on key conflict for both
bottles and agents). Dies if neither file is found or either is
invalid JSON."""
cwd_file = Path(cwd) / "claude-bottle.json"
home_file = Path(os.environ["HOME"]) / "claude-bottle.json"
cwd_doc = _load_json_or_die(cwd_file) if cwd_file.is_file() else None
home_doc = _load_json_or_die(home_file) if home_file.is_file() else None
if cwd_doc is None and home_doc is None:
die(f"no claude-bottle.json found in {cwd} or {os.environ['HOME']}")
if cwd_doc is None:
return home_doc # type: ignore[return-value]
if home_doc is None:
return cwd_doc
return {
"bottles": {**(home_doc.get("bottles") or {}), **(cwd_doc.get("bottles") or {})},
"agents": {**(home_doc.get("agents") or {}), **(cwd_doc.get("agents") or {})},
}
def _load_json_or_die(path: Path) -> Manifest:
try:
with path.open() as f:
doc = json.load(f)
except json.JSONDecodeError:
die(f"claude-bottle.json at {path} is not valid JSON")
if not isinstance(doc, dict):
die(f"claude-bottle.json at {path} must be a JSON object")
return doc
def manifest_has_agent(manifest: Manifest, name: str) -> bool:
return name in (manifest.get("agents") or {})
def manifest_require_agent(manifest: Manifest, name: str) -> None:
"""Like has_agent but dies with the available agent names listed."""
if manifest_has_agent(manifest, name):
return
available = ", ".join((manifest.get("agents") or {}).keys())
if available:
die(f"agent '{name}' not defined in claude-bottle.json. Available: {available}")
else:
die(f"agent '{name}' not defined in claude-bottle.json (manifest is empty).")
def manifest_env_names(manifest: Manifest, name: str) -> list[str]:
"""Names (not values) of bottles[agent.bottle].env, in declaration
order. Empty list if the agent has no bottle or the bottle has no env."""
agent = (manifest.get("agents") or {}).get(name) or {}
bottle_name = agent.get("bottle") or ""
if not bottle_name:
return []
bottle = (manifest.get("bottles") or {}).get(bottle_name) or {}
return list((bottle.get("env") or {}).keys())
def manifest_env_entry(manifest: Manifest, agent: str, var: str) -> str:
"""Raw string value of one env entry. Used by env_resolve, which
classifies the result by sentinel. Dies if the agent has no bottle,
or the entry is not a string."""
agent_def = (manifest.get("agents") or {}).get(agent) or {}
bottle_name = agent_def.get("bottle") or ""
if not bottle_name:
die(f"env entry {var} for agent {agent}: agent has no 'bottle' field")
bottle = (manifest.get("bottles") or {}).get(bottle_name) or {}
env = bottle.get("env") or {}
value = env.get(var)
if not isinstance(value, str):
actual = _json_type(value)
die(
f"env entry {var} for agent {agent} must be a JSON string "
f"(was {actual}). Use \"?<message>\" for prompt-at-runtime."
)
return value
def manifest_skills(manifest: Manifest, name: str) -> list[str]:
agent = (manifest.get("agents") or {}).get(name) or {}
return list(agent.get("skills") or [])
def manifest_prompt(manifest: Manifest, name: str) -> str:
agent = (manifest.get("agents") or {}).get(name) or {}
return agent.get("prompt") or ""
def manifest_agent_bottle(manifest: Manifest, name: str) -> str:
agent = (manifest.get("agents") or {}).get(name) or {}
return agent.get("bottle") or ""
def manifest_has_bottle(manifest: Manifest, bottle_name: str) -> bool:
return bottle_name in (manifest.get("bottles") or {})
def manifest_require_bottle(manifest: Manifest, bottle_name: str) -> None:
if manifest_has_bottle(manifest, bottle_name):
return
available = ", ".join((manifest.get("bottles") or {}).keys())
if available:
die(
f"bottle '{bottle_name}' not defined in claude-bottle.json. "
f"Available bottles: {available}"
)
else:
die(f"bottle '{bottle_name}' not defined in claude-bottle.json (no bottles defined).")
def manifest_bottle_ssh(manifest: Manifest, bottle_name: str) -> list[dict[str, Any]]:
bottle = (manifest.get("bottles") or {}).get(bottle_name) or {}
return list(bottle.get("ssh") or [])
def manifest_bottle_egress_allowlist(manifest: Manifest, bottle_name: str) -> list[str]:
"""Hostnames in bottles[bottle_name].egress.allowlist. Dies if the
field is present but not an array. Per-element string typing is
re-checked at use-time in pipelock."""
bottle = (manifest.get("bottles") or {}).get(bottle_name) or {}
allowlist = (bottle.get("egress") or {}).get("allowlist")
if allowlist is None:
return []
if not isinstance(allowlist, list):
die(
f"bottle '{bottle_name}' egress.allowlist must be an array "
f"(was {_json_type(allowlist)})."
)
return list(allowlist)
def manifest_ssh(manifest: Manifest, agent_name: str) -> list[dict[str, Any]]:
"""SSH entries resolved via the agent's "bottle" field; empty if no bottle set."""
bottle_name = manifest_agent_bottle(manifest, agent_name)
if not bottle_name:
return []
return manifest_bottle_ssh(manifest, bottle_name)
def _json_type(value: Any) -> str:
"""Mirror jq's type names for parity with the bash error messages."""
if value is None:
return "null"
if isinstance(value, bool):
return "boolean"
if isinstance(value, (int, float)):
return "number"
if isinstance(value, str):
return "string"
if isinstance(value, list):
return "array"
if isinstance(value, dict):
return "object"
return type(value).__name__
claude_bottle/network.py
+107
View File
@@ -0,0 +1,107 @@
"""Docker network plumbing for the per-agent egress-proxy topology.
The agent container sits on a Docker `--internal` network (no default
gateway). Pipelock straddles that network and a per-agent user-defined
bridge for upstream egress. We deliberately do NOT use Docker's legacy
`bridge` network because only user-defined bridges run Docker's
embedded DNS resolver, which pipelock needs to resolve api.anthropic.com
and similar upstream hostnames.
Naming: claude-bottle-net-<slug> (internal),
claude-bottle-egress-<slug> (egress). Numeric suffix on conflict
(-2, -3, ..., capped at 100).
"""
from __future__ import annotations
import subprocess
from .log import die, info, warn
def network_name_for_slug(slug: str) -> str:
return f"claude-bottle-net-{slug}"
def network_egress_name_for_slug(slug: str) -> str:
return f"claude-bottle-egress-{slug}"
def network_exists(name: str) -> bool:
"""Uses `docker network inspect`, not `docker network ls -f name=...`,
because the latter does substring matching."""
return (
subprocess.run(
["docker", "network", "inspect", name],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
).returncode
== 0
)
def _network_create_with_prefix(base: str, internal: bool) -> str:
"""Create a per-agent Docker network whose name is <base> (with
-2, -3, ... appended on conflict, capped at 100). Returns the
resolved name."""
name = base
suffix = 2
while network_exists(name):
name = f"{base}-{suffix}"
suffix += 1
if suffix > 100:
die(
f"could not find a free network name after {base}-99; "
f"clean up old networks with 'docker network rm <name>'"
)
kind = "internal" if internal else "bridge (egress)"
args = ["docker", "network", "create"]
if internal:
args.append("--internal")
args.append(name)
info(f"creating {kind} network {name}")
result = subprocess.run(args, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
if result.returncode != 0:
flag = " --internal" if internal else ""
die(f"docker network create{flag} {name} failed")
return name
def network_create_internal(slug: str) -> str:
"""Create a Docker `--internal` network for the agent. Returns the
resolved name."""
return _network_create_with_prefix(network_name_for_slug(slug), internal=True)
def network_create_egress(slug: str) -> str:
"""Create a per-agent user-defined bridge (NOT the legacy `bridge`)
so the pipelock sidecar has working DNS for upstream hostnames."""
return _network_create_with_prefix(network_egress_name_for_slug(slug), internal=False)
def network_attach(network: str, container: str) -> None:
result = subprocess.run(
["docker", "network", "connect", network, container],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
)
if result.returncode != 0:
die(f"docker network connect {network} {container} failed")
def network_remove(name: str) -> bool:
"""Idempotent: a missing network is treated as success so this can
be called from a teardown trap. Returns True if removal succeeded
(or the network was already gone)."""
if not network_exists(name):
return True
result = subprocess.run(
["docker", "network", "rm", name],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
)
if result.returncode != 0:
warn(f"failed to remove network {name}; clean up with 'docker network rm {name}'")
return False
return True
claude_bottle/pipelock.py
+274
View File
@@ -0,0 +1,274 @@
"""Pipelock sidecar lifecycle for the per-agent egress topology.
Pipelock (https://github.com/luckyPipewrench/pipelock) is an HTTP
forward proxy with hostname allowlisting + DLP scanning + URL-entropy
checks. One sidecar per agent, attached to the agent's --internal
network and a per-agent user-defined egress bridge. Combined with
HTTPS_PROXY/HTTP_PROXY pointing at the sidecar's service name, pipelock
is the only egress route the agent has.
Image pin: ghcr.io/luckypipewrench/pipelock@sha256:<digest> for tag 2.3.0.
"""
from __future__ import annotations
import os
import re
import subprocess
from pathlib import Path
from .log import die, info, warn
from .manifest import Manifest, manifest_bottle_egress_allowlist, manifest_bottle_ssh
# Pipelock image, pinned by digest. The digest is the multi-arch image
# index for ghcr.io/luckypipewrench/pipelock:2.3.0.
PIPELOCK_IMAGE = os.environ.get(
"CLAUDE_BOTTLE_PIPELOCK_IMAGE",
"ghcr.io/luckypipewrench/pipelock@sha256:3b1a39417b98406ddc5dc2d8fcb42865ddc0c68a43d355db55f0f8cb06bc6de9",
)
# Listening port for pipelock's forward proxy.
PIPELOCK_PORT = os.environ.get("CLAUDE_BOTTLE_PIPELOCK_PORT", "8888")
# Baked-in default allowlist for hosts Claude Code itself needs.
DEFAULT_ALLOWLIST: tuple[str, ...] = (
"api.anthropic.com",
"statsig.anthropic.com",
"sentry.io",
"claude.ai",
"platform.claude.com",
"downloads.claude.ai",
"raw.githubusercontent.com",
)
def pipelock_container_name(slug: str) -> str:
return f"claude-bottle-pipelock-{slug}"
def pipelock_proxy_url(slug: str) -> str:
return f"http://{pipelock_container_name(slug)}:{PIPELOCK_PORT}"
def pipelock_proxy_host_port(slug: str) -> str:
return f"{pipelock_container_name(slug)}:{PIPELOCK_PORT}"
# --- Allowlist resolution --------------------------------------------------
def pipelock_bottle_allowlist(manifest: Manifest, bottle_name: str) -> list[str]:
"""Hostnames in bottles[<bottle_name>].egress.allowlist. Validates
that each entry is a string."""
raw = manifest_bottle_egress_allowlist(manifest, bottle_name)
for entry in raw:
if not isinstance(entry, str):
t = _json_type(entry)
die(f"bottle '{bottle_name}' egress.allowlist must contain only strings; found a '{t}' entry.")
return list(raw)
def pipelock_bottle_ssh_hostnames(manifest: Manifest, bottle_name: str) -> list[str]:
out: list[str] = []
for entry in manifest_bottle_ssh(manifest, bottle_name):
h = entry.get("Hostname") or ""
if h:
out.append(h)
return out
_IPV4_RE = re.compile(r"^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$")
def is_ipv4_literal(s: str) -> bool:
"""Pipelock's SSRF check fires on resolved IP, so an IP-literal
Hostname goes to ssrf.ip_allowlist while a hostname goes to
trusted_domains."""
if not s:
return False
return bool(_IPV4_RE.match(s))
def pipelock_bottle_ssh_trusted_domains(manifest: Manifest, bottle_name: str) -> list[str]:
return [h for h in pipelock_bottle_ssh_hostnames(manifest, bottle_name) if not is_ipv4_literal(h)]
def pipelock_bottle_ssh_ip_cidrs(manifest: Manifest, bottle_name: str) -> list[str]:
return [f"{h}/32" for h in pipelock_bottle_ssh_hostnames(manifest, bottle_name) if is_ipv4_literal(h)]
def pipelock_effective_allowlist(manifest: Manifest, bottle_name: str) -> list[str]:
"""Deduplicated union of: baked-in defaults, bottle.egress.allowlist,
bottle.ssh[].Hostname. Sorted for stability."""
seen: dict[str, None] = {}
for h in DEFAULT_ALLOWLIST:
seen.setdefault(h, None)
for h in pipelock_bottle_allowlist(manifest, bottle_name):
if h:
seen.setdefault(h, None)
for h in pipelock_bottle_ssh_hostnames(manifest, bottle_name):
if h:
seen.setdefault(h, None)
return sorted(seen.keys())
def pipelock_allowlist_summary(manifest: Manifest, bottle_name: str) -> str:
"""One-line summary for the y/N preflight display:
"<N> hosts allowed (host1, host2, host3, +M more)"."""
hosts = pipelock_effective_allowlist(manifest, bottle_name)
count = len(hosts)
if count == 0:
return "0 hosts allowed (none)"
show = count
more = 0
if count > 5:
show = 3
more = count - show
joined = ", ".join(hosts[:show])
if more > 0:
return f"{count} hosts allowed ({joined}, +{more} more)"
return f"{count} hosts allowed ({joined})"
# --- YAML generation -------------------------------------------------------
def pipelock_write_yaml(manifest: Manifest, bottle_name: str, out_path: Path) -> None:
"""Write a pipelock YAML config (mode 600) carrying:
- the effective allowlist (hostnames),
- a fixed listen port,
- strict mode + forward_proxy.enabled + DLP defaults + scan_env.
Deliberately contains no env values, no secrets, no per-agent
customization beyond the hostname list."""
allowlist = pipelock_effective_allowlist(manifest, bottle_name)
trusted = pipelock_bottle_ssh_trusted_domains(manifest, bottle_name)
ip_cidrs = pipelock_bottle_ssh_ip_cidrs(manifest, bottle_name)
lines: list[str] = []
lines.append("version: 1")
lines.append("mode: strict")
lines.append("enforce: true")
lines.append("")
lines.append("# Hostnames the agent is allowed to reach. Effective list is")
lines.append("# claude-bottle defaults UNION bottle.egress.allowlist (sorted, deduped).")
lines.append("api_allowlist:")
for h in allowlist:
lines.append(f' - "{h}"')
lines.append("")
lines.append("forward_proxy:")
lines.append(" enabled: true")
lines.append("")
if trusted:
lines.append("trusted_domains:")
for td in trusted:
lines.append(f' - "{td}"')
lines.append("")
if ip_cidrs:
lines.append("ssrf:")
lines.append(" ip_allowlist:")
for cidr in ip_cidrs:
lines.append(f' - "{cidr}"')
lines.append("")
lines.append("dlp:")
lines.append(" include_defaults: true")
lines.append(" scan_env: true")
out_path.write_text("\n".join(lines) + "\n")
out_path.chmod(0o600)
# --- Sidecar lifecycle -----------------------------------------------------
def pipelock_start(
slug: str,
internal_network: str,
egress_network: str,
yaml_dir: Path,
yaml_filename: str,
) -> str:
"""Boot the pipelock sidecar:
1. `docker create` on the internal network with the canonical name
and argv `run --config /etc/pipelock.yaml --listen 0.0.0.0:<port>`.
2. `docker cp` the YAML config to /etc/pipelock.yaml in the
writable layer (parent dir must already exist; image is distroless).
3. Attach to the per-agent egress network.
4. `docker start`.
Returns the container name."""
name = pipelock_container_name(slug)
host_yaml = yaml_dir / yaml_filename
if not host_yaml.is_file():
die(f"pipelock yaml not found at {host_yaml}; pipelock_write_yaml must run first")
info(f"starting pipelock sidecar {name} on network {internal_network}")
create_args = [
"docker", "create",
"--name", name,
"--network", internal_network,
PIPELOCK_IMAGE,
"run", "--config", "/etc/pipelock.yaml",
"--listen", f"0.0.0.0:{PIPELOCK_PORT}",
]
if subprocess.run(create_args, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL).returncode != 0:
die(f"failed to create pipelock sidecar {name}")
cp_result = subprocess.run(
["docker", "cp", str(host_yaml), f"{name}:/etc/pipelock.yaml"],
capture_output=True,
text=True,
)
if cp_result.returncode != 0:
subprocess.run(["docker", "rm", "-f", name], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
die(f"failed to copy pipelock yaml into {name}: {cp_result.stderr.strip()}")
if subprocess.run(
["docker", "network", "connect", egress_network, name],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
).returncode != 0:
subprocess.run(["docker", "rm", "-f", name], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
die(f"failed to attach pipelock sidecar {name} to egress network {egress_network}")
if subprocess.run(
["docker", "start", name],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
).returncode != 0:
subprocess.run(["docker", "rm", "-f", name], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
die(f"failed to start pipelock sidecar {name}")
return name
def pipelock_stop(slug: str) -> None:
"""Idempotent: missing container is success."""
name = pipelock_container_name(slug)
if subprocess.run(
["docker", "inspect", name],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
).returncode == 0:
if subprocess.run(
["docker", "rm", "-f", name],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL,
).returncode != 0:
warn(f"failed to remove pipelock sidecar {name}; clean up with 'docker rm -f {name}'")
def _json_type(value: object) -> str:
if value is None:
return "null"
if isinstance(value, bool):
return "boolean"
if isinstance(value, (int, float)):
return "number"
if isinstance(value, str):
return "string"
if isinstance(value, list):
return "array"
if isinstance(value, dict):
return "object"
return type(value).__name__
claude_bottle/skills.py
+76
View File
@@ -0,0 +1,76 @@
"""Skill copier: host's ~/.claude/skills/<name>/ -> container's
~/.claude/skills/<name>/, preserving directory structure."""
from __future__ import annotations
import os
import subprocess
from .log import die, info
CONTAINER_HOME = os.environ.get("CLAUDE_BOTTLE_CONTAINER_HOME", "/home/node")
CONTAINER_SKILLS_DIR = os.environ.get(
"CLAUDE_BOTTLE_CONTAINER_SKILLS_DIR", f"{CONTAINER_HOME}/.claude/skills"
)
def host_skill_dir(name: str) -> str:
home = os.environ.get("HOME")
if not home:
die("HOME not set")
return f"{home}/.claude/skills/{name}"
def host_skill_exists(name: str) -> bool:
return os.path.isdir(host_skill_dir(name))
def require_host_skill(name: str) -> None:
if not host_skill_exists(name):
die(
f"skill '{name}' not found on host at {host_skill_dir(name)}. "
f"Create it under ~/.claude/skills/, then re-run."
)
def skills_validate_all(names: list[str]) -> None:
"""Use BEFORE the y/N so the user does not get asked about a plan
that's already known to fail."""
for n in names:
require_host_skill(n)
def skills_copy_into(container: str, names: list[str]) -> None:
"""For each named skill, ensure the parent dir exists, wipe any
prior copy, then `docker cp <host>/. <container>:<dst>/` so the
contents are copied into a freshly-created destination dir."""
if not names:
return
subprocess.run(
["docker", "exec", container, "mkdir", "-p", CONTAINER_SKILLS_DIR],
stdout=subprocess.DEVNULL,
check=True,
)
for n in names:
src = host_skill_dir(n)
if not os.path.isdir(src):
die(f"skill '{n}' disappeared from host between validation and copy at {src}.")
dst = f"{CONTAINER_SKILLS_DIR}/{n}"
info(f"copying skill {n} into {container}:{dst}")
subprocess.run(
["docker", "exec", container, "rm", "-rf", dst],
stdout=subprocess.DEVNULL,
check=True,
)
subprocess.run(
["docker", "exec", container, "mkdir", "-p", dst],
stdout=subprocess.DEVNULL,
check=True,
)
subprocess.run(
["docker", "cp", f"{src}/.", f"{container}:{dst}/"],
stdout=subprocess.DEVNULL,
check=True,
)
claude_bottle/ssh.py
+209
View File
@@ -0,0 +1,209 @@
"""SSH helpers. Validates ssh entries from claude-bottle.json, then sets
up SSH inside the container via a root-owned ssh-agent so the `node`
user can use the keys for SSH but cannot read the key bytes.
Why an in-container agent (not bind-mounted from host): Docker Desktop
on macOS does not forward Unix-domain socket connect() across the VM
boundary — connect() returns ENOTSUP. Running ssh-agent inside the
container sidesteps that entirely.
Isolation:
- Keys live at /root/.claude-bottle-keys/ (mode 700, root-owned).
/root is mode 700 in node:22-slim, so node (uid 1000) can't even
traverse in.
- ssh-agent runs as root, listening on /run/claude-bottle-agent.sock.
Each key is loaded with ssh-add, then deleted; the bytes now live
only in the agent process's memory.
- ssh-agent's SO_PEERCRED-based UID match rejects every connection
whose peer euid is neither 0 nor the agent's. To bridge that, a
root-owned socat forwarder listens on
/run/claude-bottle-agent-public.sock (mode 666) and proxies bytes
to the real agent socket.
- node can't ptrace root-owned agent or socat, so /proc/<pid>/mem is
off-limits and key bytes never leave root-owned memory.
- ~/.ssh/config in node's home points each Host at the public socket
via IdentityAgent.
Limitation: keys must be passphrase-less. ssh-add prompts on /dev/tty
for passphrases, but our docker exec has no TTY.
Each ssh entry has keys: Host, IdentityFile, Hostname, User, Port
(required); KnownHostKey (optional).
"""
from __future__ import annotations
import os
import subprocess
from pathlib import Path
from typing import Any
from .log import die, info
def ssh_validate_entries(entries: list[dict[str, Any]]) -> None:
"""Each entry must have Host + IdentityFile, and the IdentityFile
must exist on the host (after expanding leading ~)."""
for entry in entries:
name = entry.get("Host", "")
key = entry.get("IdentityFile", "")
if not name:
die(f"ssh entry missing required field 'Host': {entry}")
if not key:
die(f"ssh entry '{name}' missing required field 'IdentityFile'")
key = _expand_tilde(key)
if not os.path.isfile(key):
die(f"ssh key file not found for host '{name}': {key}")
def ssh_setup(
container: str,
stage_dir: Path,
proxy_host_port: str,
entries: list[dict[str, Any]],
) -> None:
"""Set up SSH in the container so node can authenticate using each
entry's key without the key file being readable by node."""
container_home = os.environ.get("CLAUDE_BOTTLE_CONTAINER_HOME", "/home/node")
container_ssh = f"{container_home}/.ssh"
agent_socket = "/run/claude-bottle-agent.sock"
public_socket = "/run/claude-bottle-agent-public.sock"
keys_dir = "/root/.claude-bottle-keys"
# ~/.ssh for node (700, owned by node).
_docker_exec_root(container, ["mkdir", "-p", container_ssh])
_docker_exec_root(container, ["chown", "node:node", container_ssh])
_docker_exec_root(container, ["chmod", "700", container_ssh])
# /root/.claude-bottle-keys for root (700, root-owned).
_docker_exec_root(container, ["mkdir", "-p", keys_dir])
_docker_exec_root(container, ["chown", "root:root", keys_dir])
_docker_exec_root(container, ["chmod", "700", keys_dir])
config_file = stage_dir / "ssh_config"
known_hosts_file = stage_dir / "ssh_known_hosts"
config_file.write_text("")
config_file.chmod(0o600)
known_hosts_file.write_text("")
known_hosts_file.chmod(0o600)
proxy_host, _, proxy_port = proxy_host_port.partition(":")
container_key_paths: list[str] = []
for entry in entries:
name = entry["Host"]
key = _expand_tilde(entry["IdentityFile"])
hostname = entry["Hostname"]
user = entry["User"]
port = str(entry["Port"])
known_host_key = entry.get("KnownHostKey", "")
key_basename = os.path.basename(key)
container_key_path = f"{keys_dir}/{key_basename}"
info(f"copying ssh key for '{name}' -> {container} (root-only staging)")
subprocess.run(
["docker", "cp", key, f"{container}:{container_key_path}"],
stdout=subprocess.DEVNULL,
check=True,
)
_docker_exec_root(container, ["chown", "root:root", container_key_path])
_docker_exec_root(container, ["chmod", "600", container_key_path])
container_key_paths.append(container_key_path)
# ProxyCommand tunnels SSH through pipelock via HTTP CONNECT.
# %h / %p expand to this block's HostName / Port. socat's
# PROXY: mode does CONNECT host:port to the proxy.
block = (
f"Host {name}\n"
f" HostName {hostname}\n"
f" User {user}\n"
f" Port {port}\n"
f" IdentityAgent {public_socket}\n"
f" ProxyCommand socat - PROXY:{proxy_host}:%h:%p,proxyport={proxy_port}\n"
f"\n"
)
with config_file.open("a") as f:
f.write(block)
if known_host_key:
entries_to_write: list[str] = []
if port == "22":
entries_to_write.append(f"{name} {known_host_key}\n")
if hostname != name:
entries_to_write.append(f"{hostname} {known_host_key}\n")
else:
entries_to_write.append(f"[{name}]:{port} {known_host_key}\n")
if hostname != name:
entries_to_write.append(f"[{hostname}]:{port} {known_host_key}\n")
with known_hosts_file.open("a") as f:
for e in entries_to_write:
f.write(e)
# Boot the agent, load each key, delete the key files, then start
# the root-owned socat forwarder. One docker exec so the whole
# sequence is atomic.
info(f"starting in-container ssh-agent at {agent_socket} (forwarded via {public_socket})")
setup_lines = [
"set -eu",
f"ssh-agent -a {agent_socket} >/dev/null",
]
for kp in container_key_paths:
setup_lines.append(f"SSH_AUTH_SOCK={agent_socket} ssh-add {kp}")
setup_lines.append(f"rm -f {kp}")
setup_lines.append(f"rmdir {keys_dir} 2>/dev/null || true")
# Forwarder: socat (uid 0) connects to the agent on node's behalf.
setup_lines.append(
f"nohup socat UNIX-LISTEN:{public_socket},fork,reuseaddr,mode=666 "
f"UNIX-CONNECT:{agent_socket} </dev/null >/dev/null 2>&1 &"
)
# Wait briefly for the forwarder to bind.
setup_lines.extend([
"i=0",
"while [ $i -lt 20 ]; do",
f" [ -S {public_socket} ] && break",
" i=$((i + 1))",
" sleep 0.1",
"done",
f"[ -S {public_socket} ] || {{ echo 'claude-bottle: socat forwarder failed to bind {public_socket}' >&2; exit 1; }}",
])
setup_script = "\n".join(setup_lines) + "\n"
subprocess.run(
["docker", "exec", "-u", "0", container, "sh", "-c", setup_script],
check=True,
)
info(f"writing {container_ssh}/config")
subprocess.run(
["docker", "cp", str(config_file), f"{container}:{container_ssh}/config"],
stdout=subprocess.DEVNULL,
check=True,
)
_docker_exec_root(container, ["chown", "node:node", f"{container_ssh}/config"])
_docker_exec_root(container, ["chmod", "600", f"{container_ssh}/config"])
if known_hosts_file.stat().st_size > 0:
info(f"writing {container_ssh}/known_hosts")
subprocess.run(
["docker", "cp", str(known_hosts_file), f"{container}:{container_ssh}/known_hosts"],
stdout=subprocess.DEVNULL,
check=True,
)
_docker_exec_root(container, ["chown", "node:node", f"{container_ssh}/known_hosts"])
_docker_exec_root(container, ["chmod", "600", f"{container_ssh}/known_hosts"])
def _docker_exec_root(container: str, argv: list[str]) -> None:
subprocess.run(
["docker", "exec", "-u", "0", container, *argv],
stdout=subprocess.DEVNULL,
check=True,
)
def _expand_tilde(path: str) -> str:
if path.startswith("~"):
home = os.environ.get("HOME", "")
return home + path[1:]
return path