agentboxer 1.0.1__py3-none-any.whl

agentbox/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

agentbox/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

agentbox/cli.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from . import config as cfg
+
+DEVCONTAINER_CLI = ["npx", "--yes", "@devcontainers/cli"]
+CONTAINER_USER = "dev"
+CONTAINER_SSH_PORT = 2222
+EDITORS = ("code-oss", "codium", "code")
+GITIGNORE_ENTRY = cfg.MERGED_IN_PROJECT
+UP_BINARIES = ("docker", "npx", "ssh-keygen")
+EXEC_BINARIES = ("docker", "npx")
+
+
+def missing_binaries(names: tuple[str, ...]) -> list[str]:
+    return [name for name in names if shutil.which(name) is None]
+
+
+def require_binaries(names: tuple[str, ...]) -> int:
+    missing = missing_binaries(names)
+    if not missing:
+        return 0
+    print(f"✖ missing on this host: {', '.join(missing)}", file=sys.stderr)
+    print(f"  agentbox needs: {', '.join(names)}", file=sys.stderr)
+    return 3
+
+
+def state_dir() -> Path:
+    override = os.environ.get("AGENTBOX_HOME")
+    if override:
+        return Path(override)
+    return Path.home() / ".config" / "agentbox"
+
+
+def ssh_dir(state: Path) -> Path:
+    return state / "ssh.d"
+
+
+def include_line(state: Path) -> str:
+    return f"Include {ssh_dir(state)}/*.conf"
+
+
+def _capture(cmd: list[str]) -> str:
+    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+    return result.stdout.strip()
+
+
+def container_id(workspace: Path) -> str | None:
+    label = f"label=devcontainer.local_folder={workspace.resolve()}"
+    out = _capture(["docker", "ps", "-aq", "--filter", label])
+    ids = out.splitlines()
+    if not ids:
+        return None
+    return ids[0]
+
+
+def ssh_port(cid: str) -> int:
+    out = _capture(["docker", "port", cid, f"{CONTAINER_SSH_PORT}/tcp"])
+    first = out.splitlines()[0]
+    return int(first.rsplit(":", 1)[1])
+
+
+def ensure_key(state: Path, alias: str) -> Path:
+    key_file = state / "keys" / alias / "id_ed25519"
+    if key_file.exists():
+        return key_file
+    key_file.parent.mkdir(parents=True, exist_ok=True)
+    subprocess.run(
+        [
+            "ssh-keygen",
+            "-q",
+            "-t",
+            "ed25519",
+            "-N",
+            "",
+            "-C",
+            f"agentbox-{alias}",
+            "-f",
+            str(key_file),
+        ],
+        check=True,
+    )
+    return key_file
+
+
+def exec_command(workspace: Path, override: Path | None, command: list[str]) -> list[str]:
+    prefix = [*DEVCONTAINER_CLI, "exec", "--workspace-folder", str(workspace)]
+    if override is not None:
+        prefix += ["--override-config", str(override)]
+    return [*prefix, *command]
+
+
+def inject_key(workspace: Path, override: Path | None, key_file: Path) -> None:
+    remote = (
+        "mkdir -p ~/.ssh && chmod 700 ~/.ssh && "
+        "cat >~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
+    )
+    subprocess.run(
+        exec_command(workspace, override, ["bash", "-c", remote]),
+        input=key_file.with_suffix(".pub").read_text(encoding="utf-8"),
+        text=True,
+        check=True,
+    )
+
+
+def alias_dir(state: Path) -> Path:
+    return state / "aliases"
+
+
+def claim_alias(workspace: Path, state: Path) -> str:
+    alias = cfg.alias_for(workspace, alias_dir(state))
+    cfg.claim_alias(alias_dir(state), alias, workspace)
+    return alias
+
+
+def alias_for(workspace: Path, state: Path) -> str:
+    return cfg.alias_for(workspace, alias_dir(state))
+
+
+def write_ssh_config(state: Path, alias: str, port: int, key_file: Path) -> bool:
+    target = ssh_dir(state) / f"{alias}.conf"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(
+        cfg.ssh_config_block(alias, port, key_file, CONTAINER_USER),
+        encoding="utf-8",
+    )
+    user_config = Path.home() / ".ssh" / "config"
+    try:
+        return include_line(state) in user_config.read_text(encoding="utf-8")
+    except OSError:
+        return False
+
+
+def up_command(workspace: Path, override: Path | None, rebuild: bool) -> list[str]:
+    command = [*DEVCONTAINER_CLI, "up", "--workspace-folder", str(workspace)]
+    if override is not None:
+        command += ["--override-config", str(override)]
+        if not override.is_relative_to(workspace):
+            command += ["--no-lockfile"]
+    if rebuild:
+        command += ["--remove-existing-container"]
+    return command
+
+
+def cmd_up(args: argparse.Namespace) -> int:
+    blocked = require_binaries(UP_BINARIES)
+    if blocked:
+        return blocked
+
+    workspace = args.workspace.resolve()
+    state = state_dir()
+    alias = claim_alias(workspace, state)
+    key_file = ensure_key(state, alias)
+
+    override = cfg.resolve_config(workspace, state / "run", cfg.SHARE_DIR, alias)
+    subprocess.run(up_command(workspace, override, args.rebuild), check=True)
+
+    cid = container_id(workspace)
+    if cid is None:
+        print("✖ container not found after up", file=sys.stderr)
+        return 1
+
+    inject_key(workspace, override, key_file)
+    port = ssh_port(cid)
+    included = write_ssh_config(state, alias, port, key_file)
+
+    print(f"\nagentbox '{alias}' is up on 127.0.0.1:{port}\n")
+    print("  agentbox run claude       agent inside the container")
+    print("  agentbox shell            shell inside the container")
+    print("  agentbox code             open the editor on the container\n")
+    if not included:
+        print(f"Add this line once to ~/.ssh/config, then 'ssh {alias}' works:")
+        print(f"  {include_line(state)}\n")
+    return 0
+
+
+def cmd_run(args: argparse.Namespace) -> int:
+    blocked = require_binaries(EXEC_BINARIES)
+    if blocked:
+        return blocked
+
+    workspace = args.workspace.resolve()
+    state = state_dir()
+    alias = alias_for(workspace, state)
+    override = cfg.resolve_config(workspace, state / "run", cfg.SHARE_DIR, alias)
+    return subprocess.run(exec_command(workspace, override, args.command)).returncode
+
+
+def cmd_shell(args: argparse.Namespace) -> int:
+    args.command = ["zsh"]
+    return cmd_run(args)
+
+
+def cmd_code(args: argparse.Namespace) -> int:
+    workspace = args.workspace.resolve()
+    alias = alias_for(workspace, state_dir())
+    editor = next((shutil.which(name) for name in EDITORS if shutil.which(name)), None)
+    if editor is None:
+        print(f"✖ no editor found, looked for: {', '.join(EDITORS)}", file=sys.stderr)
+        return 1
+    command = [editor, "--remote", f"ssh-remote+{alias}", cfg.workspace_target(workspace)]
+    return subprocess.run(command).returncode
+
+
+def cmd_down(args: argparse.Namespace) -> int:
+    blocked = require_binaries(("docker",))
+    if blocked:
+        return blocked
+
+    workspace = args.workspace.resolve()
+    cid = container_id(workspace)
+    if cid is None:
+        print(f"→ no agentbox container for {workspace}")
+        return 0
+    subprocess.run(["docker", "rm", "-f", cid], check=True)
+    return 0
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    workspace = args.workspace.resolve()
+    target = workspace / cfg.PROJECT_CONFIG
+    if target.exists() and not args.force:
+        print(f"✖ {target} exists, use --force to overwrite", file=sys.stderr)
+        return 1
+    config = cfg.apply_alias(
+        json.loads(cfg.BASE_CONFIG.read_text(encoding="utf-8")),
+        claim_alias(workspace, state_dir()),
+    )
+    config["postCreateCommand"] = "npm install -g $AGENTBOX_AGENTS"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+    print(f"→ wrote {target}")
+
+    gitignore = workspace / ".gitignore"
+    if gitignore.exists() and GITIGNORE_ENTRY not in gitignore.read_text(encoding="utf-8"):
+        with gitignore.open("a", encoding="utf-8") as handle:
+            handle.write(f"{GITIGNORE_ENTRY}\n")
+        print(f"→ added {GITIGNORE_ENTRY} to .gitignore")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agentbox",
+        description="Run coding agents in a per-project dev container sandbox.",
+    )
+    parser.add_argument(
+        "--workspace",
+        type=Path,
+        default=Path.cwd(),
+        help="project directory (default: current directory)",
+    )
+    subparsers = parser.add_subparsers(dest="subcommand", required=True)
+
+    up = subparsers.add_parser("up", help="build and start the sandbox")
+    up.add_argument("--rebuild", action="store_true", help="recreate an existing container")
+    up.set_defaults(func=cmd_up)
+
+    run = subparsers.add_parser("run", help="run a command inside the sandbox")
+    run.add_argument("command", nargs=argparse.REMAINDER)
+    run.set_defaults(func=cmd_run)
+
+    subparsers.add_parser("shell", help="open a shell inside the sandbox").set_defaults(
+        func=cmd_shell
+    )
+    subparsers.add_parser("code", help="open the editor on the sandbox").set_defaults(
+        func=cmd_code
+    )
+    subparsers.add_parser("down", help="remove the sandbox container").set_defaults(
+        func=cmd_down
+    )
+
+    init = subparsers.add_parser("init", help="write a project devcontainer.json")
+    init.add_argument("--force", action="store_true", help="overwrite an existing config")
+    init.set_defaults(func=cmd_init)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.subcommand == "run" and not args.command:
+        print("✖ agentbox run needs a command", file=sys.stderr)
+        return 2
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agentbox/config.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from pathlib import Path
+
+SHARE_DIR = Path(__file__).resolve().parent / "share"
+BASE_CONFIG = SHARE_DIR / "devcontainer.base.json"
+POST_CREATE = "bash /agentbox/post-create.sh"
+SHARE_MOUNT_TARGET = "/agentbox"
+PROJECT_CONFIG = ".devcontainer/devcontainer.json"
+LOCAL_OVERRIDE = ".devcontainer/agentbox.local.json"
+MERGED_IN_PROJECT = ".devcontainer/.agentbox.json"
+BASENAME_PLACEHOLDER = "${localWorkspaceFolderBasename}"
+DIGEST_LENGTH = 6
+
+
+def alias_registry(registry_dir: Path | None) -> dict[str, Path]:
+    if registry_dir is None or not registry_dir.is_dir():
+        return {}
+    return {
+        entry.name: Path(entry.read_text(encoding="utf-8").strip())
+        for entry in sorted(registry_dir.iterdir())
+        if entry.is_file()
+    }
+
+
+def claim_alias(registry_dir: Path, alias: str, workspace: Path) -> None:
+    registry_dir.mkdir(parents=True, exist_ok=True)
+    (registry_dir / alias).write_text(f"{workspace.resolve()}\n", encoding="utf-8")
+
+
+def alias_for(workspace: Path, registry_dir: Path | None = None) -> str:
+    workspace = workspace.resolve()
+    slug = re.sub(r"[^A-Za-z0-9._-]", "-", workspace.name).strip("-")
+    if not slug:
+        raise ValueError(f"cannot derive an alias from {workspace}")
+
+    registry = alias_registry(registry_dir)
+    for alias, owner in registry.items():
+        if owner == workspace:
+            return alias
+
+    if slug not in registry:
+        return slug
+
+    digest = hashlib.sha256(str(workspace).encode("utf-8")).hexdigest()[:DIGEST_LENGTH]
+    return f"{slug}-{digest}"
+
+
+def apply_alias(config: dict, alias: str) -> dict:
+    config["name"] = alias
+    mounts = config.get("mounts")
+    if mounts:
+        config["mounts"] = [
+            mount.replace(BASENAME_PLACEHOLDER, alias) for mount in mounts
+        ]
+    return config
+
+
+def workspace_target(workspace: Path) -> str:
+    return f"/workspaces/{workspace.resolve().name}"
+
+
+def deep_merge(base: dict, override: dict) -> dict:
+    merged = dict(base)
+    for key, value in override.items():
+        current = merged.get(key)
+        if isinstance(current, dict) and isinstance(value, dict):
+            merged[key] = deep_merge(current, value)
+        else:
+            merged[key] = value
+    return merged
+
+
+def _read_json(path: Path) -> dict:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def base_config(share_dir: Path, alias: str) -> dict:
+    config = apply_alias(_read_json(BASE_CONFIG), alias)
+    mounts = list(config.get("mounts", []))
+    mounts.append(
+        f"source={share_dir},target={SHARE_MOUNT_TARGET},type=bind,readonly"
+    )
+    config["mounts"] = mounts
+    config["postCreateCommand"] = POST_CREATE
+    return config
+
+
+def resolve_config(workspace: Path, state_dir: Path, share_dir: Path, alias: str) -> Path | None:
+    workspace = workspace.resolve()
+    project = workspace / PROJECT_CONFIG
+    override = workspace / LOCAL_OVERRIDE
+
+    if project.exists():
+        if not override.exists():
+            return None
+        merged = deep_merge(_read_json(project), _read_json(override))
+        target = workspace / MERGED_IN_PROJECT
+        target.write_text(json.dumps(merged, indent=2) + "\n", encoding="utf-8")
+        return target
+
+    config = base_config(share_dir, alias)
+    if override.exists():
+        config = deep_merge(config, _read_json(override))
+    target = state_dir / alias / "devcontainer.json"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+    return target
+
+
+def ssh_config_block(alias: str, port: int, key_file: Path, user: str) -> str:
+    return "\n".join(
+        [
+            f"Host {alias}",
+            "  HostName 127.0.0.1",
+            f"  Port {port}",
+            f"  User {user}",
+            f"  IdentityFile {key_file}",
+            "  IdentitiesOnly yes",
+            "  StrictHostKeyChecking no",
+            "  UserKnownHostsFile /dev/null",
+            "",
+        ]
+    )

agentbox/share/devcontainer.base.json

@@ -0,0 +1,22 @@
+{
+  "image": "docker.io/library/debian:bookworm",
+  "features": {
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "username": "dev",
+      "installZsh": true,
+      "configureZshAsDefaultShell": true
+    },
+    "ghcr.io/devcontainers/features/git:1": {},
+    "ghcr.io/devcontainers/features/node:1": {},
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
+    "ghcr.io/devcontainers/features/sshd:1": {}
+  },
+  "remoteUser": "dev",
+  "appPort": ["127.0.0.1::2222"],
+  "containerEnv": {
+    "AGENTBOX_AGENTS": "@anthropic-ai/claude-code"
+  },
+  "mounts": [
+    "source=agentbox-home-${localWorkspaceFolderBasename},target=/home/dev,type=volume"
+  ]
+}

agentbox/share/post-create.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+: "${AGENTBOX_AGENTS:?set containerEnv.AGENTBOX_AGENTS in the devcontainer config}"
+
+read -r -a agents <<<"$AGENTBOX_AGENTS"
+
+if [ "${#agents[@]}" -eq 0 ]; then
+  echo "→ no agents requested"
+  exit 0
+fi
+
+echo "→ installing agents: ${agents[*]}"
+npm install -g "${agents[@]}"

agentboxer-1.0.1.dist-info/METADATA

@@ -0,0 +1,279 @@
+Metadata-Version: 2.4
+Name: agentboxer
+Version: 1.0.1
+Summary: Run coding agents in a per-project dev container sandbox.
+Author-email: Kevin Veen-Birkenbach <kevin@veen.world>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/kevinveenbirkenbach/agentbox
+Project-URL: Source, https://github.com/kevinveenbirkenbach/agentbox
+Project-URL: Issues, https://github.com/kevinveenbirkenbach/agentbox/issues
+Keywords: devcontainer,sandbox,agent,docker,claude-code
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# agentbox
+
+Run coding agents in a per-project dev container sandbox.
+
+The agent gets a container with its own Docker daemon and nothing of the host but the project directory: no host Docker socket, no host home, no sibling repositories. One command per project, no per-project boilerplate.
+
+Homepage: https://github.com/kevinveenbirkenbach/agentbox
+
+## How it fits together
+
+```mermaid
+flowchart LR
+  subgraph host["Host"]
+    editor["Code - OSS / VSCodium<br/>open-remote-ssh"]
+    cli["agentbox CLI"]
+    state["~/.config/agentbox<br/>aliases + keys + ssh.d/*.conf"]
+    dockerd["host docker daemon"]
+    repo[("project directory")]
+  end
+
+  subgraph layers["Configuration layers"]
+    base["1 base<br/>share/devcontainer.base.json"]
+    project["2 project<br/>.devcontainer/devcontainer.json"]
+    override["3 local<br/>.devcontainer/agentbox.local.json"]
+    merged["effective devcontainer.json"]
+  end
+
+  subgraph box["agentbox container"]
+    sshd["sshd on 2222"]
+    exthost["remote extension host<br/>agent extension"]
+    agent["agent CLI<br/>claude / codex / ..."]
+    dind["own docker daemon"]
+    workspace["/workspaces/PROJECT"]
+    nested["containers the agent starts"]
+  end
+
+  base --> merged
+  project --> merged
+  override --> merged
+  cli -- "deep merge" --> merged
+  merged -- "override config" --> devcli["npx @devcontainers/cli"]
+  cli --> devcli
+  devcli -- "build and start" --> dockerd
+  dockerd -- "creates" --> box
+  cli -- "ssh key, host entry" --> state
+  cli -- "agentbox run / shell" --> agent
+  editor -- "reads" --> state
+  editor -- "ssh 127.0.0.1 on a free port" --> sshd
+  sshd --> exthost
+  exthost <-- "~/.claude/ide + localhost" --> agent
+  agent --> workspace
+  agent --> dind
+  dind --> nested
+  repo -- "bind mount" --> workspace
+```
+
+What the picture says:
+
+- The agent only ever reaches `/workspaces/PROJECT`, which is the bind-mounted project directory. No host home, no sibling repositories.
+- The container talks to its **own** Docker daemon. The host daemon is used once, by the CLI, to create the sandbox — the agent never gets a handle on it.
+- The agent extension runs in the container, next to the agent CLI, because the two communicate over `~/.claude/ide` plus localhost. An extension host on the host side cannot reach either.
+- The three configuration layers are merged on the host and handed to the devcontainer CLI as one file; nothing has to be edited by hand.
+
+## Install
+
+```bash
+pipx install agentboxer
+```
+
+The distribution is named `agentboxer` because `agentbox` is taken on PyPI and `agentbox-cli` collides with an existing project once PyPI strips the separators; the command it installs is `agentbox`.
+
+Independent of PyPI, from a checkout:
+
+```bash
+make install
+```
+
+The package itself has no Python dependencies, but it drives three host binaries and refuses to start without them:
+
+| Binary | Used for |
+|---|---|
+| `docker` | building and running the sandbox |
+| `npx` (Node.js) | fetching the [devcontainer CLI](https://github.com/devcontainers/cli) |
+| `ssh-keygen` | the per-project key |
+
+## Quickstart
+
+```bash
+cd ~/Repositories/some-project
+agentbox up
+agentbox run claude
+```
+
+`agentbox up` builds and starts the sandbox, publishes its SSH port on a free `127.0.0.1` port, installs a per-project key, and writes an SSH host entry named after the project directory.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `agentbox up [--rebuild]` | Build and start the sandbox for the current directory |
+| `agentbox run <cmd…>` | Run a command inside the sandbox, e.g. `agentbox run claude` |
+| `agentbox shell` | Open a shell inside the sandbox |
+| `agentbox code` | Open Code - OSS / VSCodium / VS Code on the sandbox |
+| `agentbox down` | Remove the sandbox container |
+| `agentbox init` | Write a project-owned `.devcontainer/devcontainer.json` |
+
+All commands accept `--workspace <dir>` and otherwise act on the current directory.
+
+## One box per repository
+
+Boxes run side by side and share nothing. Each project gets its own container, SSH port, key, host entry and agent home volume:
+
+| Resource | Keyed by |
+|---|---|
+| Container | label `devcontainer.local_folder=<absolute path>` |
+| SSH port | published by Docker on a free `127.0.0.1` port |
+| Key, host entry | `~/.config/agentbox/keys/<alias>/`, `~/.config/agentbox/ssh.d/<alias>.conf` |
+| Agent home (logins, history) | volume `agentbox-home-<alias>` |
+
+The alias is the project directory name. Two repositories with the same directory name — `~/work/web` and `~/client/web` — would otherwise collide in all of the above, so the first one to claim `web` keeps it and the next gets a path digest appended: `web-0ac1b2`. Claims live in `~/.config/agentbox/aliases/` and are sticky, so an alias never changes under a running box.
+
+Removing a box: `agentbox down`, plus `docker volume rm agentbox-home-<alias>` if its agent state should go too.
+
+## Configuration layers
+
+Later layers win; each is optional.
+
+| Layer | File | Versioned |
+|---|---|---|
+| 1. agentbox default | `src/agentbox/share/devcontainer.base.json` | in this repo |
+| 2. Project | `<project>/.devcontainer/devcontainer.json` | in the project |
+| 3. Local override | `<project>/.devcontainer/agentbox.local.json` | no, gitignore it |
+
+Layer 3 is deep-merged over whatever layer sits below it; dictionaries merge, lists and scalars are replaced. The merged result is handed to the devcontainer CLI via `--override-config`, so nothing needs to be edited by hand.
+
+Example — this project needs Codex instead of Claude and a Python toolchain, but only on this machine:
+
+```json
+{
+  "containerEnv": { "AGENTBOX_AGENTS": "@openai/codex" },
+  "features": { "ghcr.io/devcontainers/features/python:1": {} }
+}
+```
+
+Agents are npm packages listed in `AGENTBOX_AGENTS`, installed on first start.
+
+## Editor
+
+The agent extension must run inside the container, otherwise it cannot reach the agent CLI. That happens automatically once the editor window itself is remote.
+
+1. Install `jeanp413.open-remote-ssh` from Open VSX (the proprietary Dev Containers extension is not needed and is unavailable on Open VSX).
+2. Add this line once to `~/.ssh/config`:
+
+   ```
+   Include ~/.config/agentbox/ssh.d/*.conf
+   ```
+
+3. `agentbox code`, or connect manually to the host entry named after the project and open `/workspaces/<project>`.
+
+Ports change on every rebuild; `agentbox up` rewrites the host entry each time, so the alias stays valid.
+
+## Projects that already have a devcontainer.json
+
+`agentbox up` uses the project's own config unchanged. To install the agents from there, add the feature in this repository:
+
+```json
+"features": { "ghcr.io/kevinveenbirkenbach/agentbox/agentbox:0": { "agents": "@anthropic-ai/claude-code" } }
+```
+
+The feature source lives in `features/agentbox/`; publish it with `devcontainer features publish`.
+
+## Limitations
+
+- The project directory is bind-mounted, so build artifacts inside it (`.venv/`, `node_modules/`) are shared with the host and can collide between host and container toolchains. Mount them as volumes in layer 3 if that bites.
+- Containers started *inside* the sandbox run in its nested Docker daemon; their published ports are not reachable from the host.
+- Network access is not restricted yet — the sandbox isolates the filesystem and the Docker daemon, not the internet.
+- The agent CLIs themselves are proprietary; only the sandbox around them is open source.
+
+## Other agents
+
+`AGENTBOX_AGENTS` is a space separated list of npm packages installed on first start. Override it per project in `.devcontainer/agentbox.local.json`:
+
+```json
+{
+  "containerEnv": {
+    "AGENTBOX_AGENTS": "@anthropic-ai/claude-code @openai/codex @google/gemini-cli"
+  }
+}
+```
+
+Then `agentbox up --rebuild` and `agentbox run codex`. Agents that are not npm packages (pipx tools, plain binaries) have no install path yet. The Pi agent (`@oh-my-pi/pi-coding-agent`, binary `omp`) needs bun rather than node.
+
+## Local LLMs
+
+The sandbox has its own network namespace, so an Ollama or LM Studio server running on the **host** is not reachable from inside by default. Punch one hole into `.devcontainer/agentbox.local.json`:
+
+```json
+{
+  "runArgs": ["--add-host=host.docker.internal:host-gateway"],
+  "containerEnv": {
+    "OLLAMA_BASE_URL": "http://host.docker.internal:11434",
+    "OLLAMA_HOST": "http://host.docker.internal:11434"
+  }
+}
+```
+
+What each agent does with that, verified in the e2e suite below:
+
+| Agent | Ollama | LM Studio | Invocation |
+|---|---|---|---|
+| codex | yes | yes | `codex exec -c model_provider=x -c model_providers.x.base_url=<url>/v1 -c model_providers.x.wire_api=responses -c model_providers.x.requires_openai_auth=false -m <model>` |
+| pi (`omp`) | yes | catalog discovery works | `omp --model ollama/<model>` with `OLLAMA_BASE_URL` set, or `omp --model lm-studio/<model>` |
+| Claude Code | via proxy | via proxy | Anthropic protocol only — needs a translator (e.g. LiteLLM) behind `ANTHROPIC_BASE_URL` |
+
+Three constraints found the hard way, each encoded in the e2e suite:
+
+- codex accepts only `wire_api = "responses"`; the chat-completions wire was removed. Both servers implement that endpoint.
+- `codex --oss` insists on a daemon at `localhost:11434` and ignores `OLLAMA_HOST`, so a remote endpoint needs an explicit provider.
+- Agent CLIs need a model that supports tool calling. `smollm2:135m` answers plain chat requests but fails every agent.
+
+## Tests
+
+Everything at once — unit tests plus the end-to-end suite:
+
+```bash
+make test
+```
+
+Unit tests alone, no containers:
+
+```bash
+make test-unit
+```
+
+End-to-end against real local LLMs, fully isolated in compose — Ollama, LM Studio in headless server mode, and a runner carrying codex and pi. No host network, no API keys, no accounts:
+
+```bash
+make test-e2e                  # tears the stack down afterwards
+bash tests/e2e/run.sh --keep   # leaves it up for debugging
+```
+
+Models are pulled once into named volumes: `qwen2.5:0.5b` for Ollama, and for LM Studio the Hugging Face repository pinned in `tests/e2e/.env` — its CLI resolves search terms only against staff picks, so the source is a full URL rather than a name. Twelve checks then assert reachability, the native and OpenAI-compatible endpoints, and that codex and pi actually answer from a local model.
+
+The runner shares the LM Studio container's network namespace, so LM Studio sits on `localhost:1234` exactly as the agent CLIs expect while Ollama stays reachable by service name.
+
+Everything runs in CI on every push and pull request, and again before a release.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Author
+
+Kevin Veen-Birkenbach <kevin@veen.world>

agentboxer-1.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+agentbox/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+agentbox/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+agentbox/cli.py,sha256=eJXYokEwWLu2FRIqP7yQqbL7xuzp4OwXIB0jHiRm-Zk,9463
+agentbox/config.py,sha256=zHFR3luI0tag5ASYMvU5R9GJO5svpAs9GqiyXPgaSl8,4047
+agentbox/share/devcontainer.base.json,sha256=5lgLEERBxP1Bs81Qs3QNj5MMR7BB87G-VzFOfRGRdZY,672
+agentbox/share/post-create.sh,sha256=-2I6H-cpjMtZ_izobSUAZChs_0Wr244Y3wucNdTITSQ,319
+agentboxer-1.0.1.dist-info/licenses/LICENSE,sha256=HZ45yCTAIaoS9tYIZ6YbYNXkq3_7rpN5-IwPLc32_FY,1078
+agentboxer-1.0.1.dist-info/METADATA,sha256=DBtblfWE8iWBOwwKSo_6hxhdZQ26ae4R-JeDKJ94Ia8,11723
+agentboxer-1.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+agentboxer-1.0.1.dist-info/entry_points.txt,sha256=u_320LVs7Vndr2ti0gFQXhR8o9kkjW0LmNjLzEXLr50,47
+agentboxer-1.0.1.dist-info/top_level.txt,sha256=lNpen_9W4iU-XQIGpizrWb3jS7tj6k27fUBWT4u0HEQ,9
+agentboxer-1.0.1.dist-info/RECORD,,

agentboxer-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agentboxer-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agentbox = agentbox.cli:main

agentboxer-1.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Veen-Birkenbach
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agentboxer-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+agentbox