proxyagent 0.1.0__tar.gz

proxyagent-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+*.db
+.proxyagent/
+admin_token
+.env
+.DS_Store
+.pytest_cache/

proxyagent-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: proxyagent
+Version: 0.1.0
+Summary: Run any agent (Claude, Codex, custom) on any machine — with no API key on the machine. A secure, self-hosted proxy for models and tools.
+Project-URL: Homepage, https://github.com/teddyoweh/proxyagent
+Author-email: Spawn Labs <teddy@spawnlabs.ai>
+License-Expression: Apache-2.0
+Keywords: agents,claude,codex,gateway,llm,proxy,security,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn[standard]>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# proxyagent
+
+**Run any agent — Claude, Codex, custom — on any machine, with _no API key on the machine._**
+
+A secure, self-hosted proxy for models **and** tools. Your keys live in one hardened place; every machine holds only a scoped, revocable token.
+
+</div>
+
+---
+
+Agents need model access (and tool access) to do anything. Today that means scattering
+real API keys across every machine an agent runs on — a security nightmare. `proxyagent`
+fixes it: stand up **one** proxy that holds the real credentials, and point every agent at
+it. The machine gets a throwaway token; the real key never leaves the proxy.
+
+```
+   remote machine                     proxy (you host)            upstream
+ ┌────────────────┐  token only   ┌──────────────────┐  real key  ┌───────────┐
+ │ claude / codex │ ───────────►  │  proxyagent serve │ ─────────► │ Anthropic │
+ │  (no real key) │ ◄───────────  │  scope·log·tools  │ ◄───────── │  OpenAI   │
+ └────────────────┘   stream      └──────────────────┘            └───────────┘
+```
+
+## How it works
+Every harness honours `*_BASE_URL`, so the shim is trivial: point the base URL at the
+proxy and use the **machine token** as the "api key." The proxy authenticates the token,
+checks its scope, **swaps in the real key**, forwards upstream, and logs the call. The
+machine never sees a real credential.
+
+## Quickstart
+
+**1. Run the proxy** (on a box you control — it holds the real keys):
+```bash
+pip install proxyagent
+export ANTHROPIC_API_KEY=sk-ant-…      # and/or OPENAI_API_KEY=sk-…
+proxyagent serve                        # prints an admin token + a dashboard at :8080
+```
+
+**2. Mint a machine token** (scoped + revocable):
+```bash
+proxyagent token new macbook-01 --scope "anthropic:claude-*" --admin pa_admin_…
+```
+
+**3. Run any agent on any machine — no real key there:**
+```bash
+PROXYAGENT_TOKEN=pa_… proxyagent run claude-code \
+  --goal "build a SwiftUI todo app" --proxy https://proxy.you.com
+# or:  proxyagent run codex --goal "fix the failing tests" --token pa_…
+```
+
+Or use any harness directly — just set the env and the proxy does the rest:
+```bash
+export ANTHROPIC_BASE_URL=https://proxy.you.com/anthropic
+export ANTHROPIC_API_KEY=pa_…          # the machine token, not the real key
+claude -p "ship it"
+```
+
+## The dashboard
+`proxyagent serve` ships a dashboard at `/` — mint/revoke tokens, watch live usage and a
+full request audit log, see configured providers + proxied tools. Paste the admin token to
+open it.
+
+## Proxied tools — the same trick, for tools
+The proxy can also hold your **tool** keys and hand agents governed tools — so an agent gets
+web search (and custom tools) without ever holding the tool's credential.
+
+```bash
+export TAVILY_API_KEY=tvly-…                                   # web_search uses this; agents never see it
+export PROXYAGENT_TOOLS='[{"name":"crm","url":"https://hooks.you.com/crm","headers":{"Authorization":"Bearer …"}}]'
+# then send requests with header  x-proxyagent-tools: on  → tool defs are injected;
+# the proxy executes calls to managed tools server-side (keys stay here).
+```
+
+## Security model
+- **Real keys never leave the proxy** — read from env, never persisted, never logged, never returned.
+- **Machine tokens are stored hashed** (SHA-256); plaintext shown once. A stolen DB yields nothing usable.
+- **Scoped** (`provider:model` globs), **expiring** (TTL), **revocable**, **rate-limited**.
+- **Constant-time** token comparison; sensitive headers redacted from logs.
+- Admin API + dashboard gated by a separate admin token. Run it behind TLS.
+
+## SDK
+```python
+import proxyagent
+
+# host the proxy (embed in your own service):
+app = proxyagent.create_app()              # ASGI app
+
+# mint tokens programmatically:
+admin = proxyagent.Admin("https://proxy.you.com", "pa_admin_…")
+token = admin.mint("ci-runner", scope=["anthropic:claude-*"], ttl_seconds=3600)
+
+# run a harness on this machine, no key here:
+proxyagent.run("claude-code", goal="build the app",
+               proxy="https://proxy.you.com", token=token)
+```
+
+## Supported harnesses
+`claude-code`, `codex`, and any **custom** command (`--command "my-agent {goal}"`). Adding one
+is a few lines — it just needs to respect `*_BASE_URL`.
+
+## License
+Apache-2.0

proxyagent-0.1.0/README.md

@@ -0,0 +1,104 @@
+<div align="center">
+
+# proxyagent
+
+**Run any agent — Claude, Codex, custom — on any machine, with _no API key on the machine._**
+
+A secure, self-hosted proxy for models **and** tools. Your keys live in one hardened place; every machine holds only a scoped, revocable token.
+
+</div>
+
+---
+
+Agents need model access (and tool access) to do anything. Today that means scattering
+real API keys across every machine an agent runs on — a security nightmare. `proxyagent`
+fixes it: stand up **one** proxy that holds the real credentials, and point every agent at
+it. The machine gets a throwaway token; the real key never leaves the proxy.
+
+```
+   remote machine                     proxy (you host)            upstream
+ ┌────────────────┐  token only   ┌──────────────────┐  real key  ┌───────────┐
+ │ claude / codex │ ───────────►  │  proxyagent serve │ ─────────► │ Anthropic │
+ │  (no real key) │ ◄───────────  │  scope·log·tools  │ ◄───────── │  OpenAI   │
+ └────────────────┘   stream      └──────────────────┘            └───────────┘
+```
+
+## How it works
+Every harness honours `*_BASE_URL`, so the shim is trivial: point the base URL at the
+proxy and use the **machine token** as the "api key." The proxy authenticates the token,
+checks its scope, **swaps in the real key**, forwards upstream, and logs the call. The
+machine never sees a real credential.
+
+## Quickstart
+
+**1. Run the proxy** (on a box you control — it holds the real keys):
+```bash
+pip install proxyagent
+export ANTHROPIC_API_KEY=sk-ant-…      # and/or OPENAI_API_KEY=sk-…
+proxyagent serve                        # prints an admin token + a dashboard at :8080
+```
+
+**2. Mint a machine token** (scoped + revocable):
+```bash
+proxyagent token new macbook-01 --scope "anthropic:claude-*" --admin pa_admin_…
+```
+
+**3. Run any agent on any machine — no real key there:**
+```bash
+PROXYAGENT_TOKEN=pa_… proxyagent run claude-code \
+  --goal "build a SwiftUI todo app" --proxy https://proxy.you.com
+# or:  proxyagent run codex --goal "fix the failing tests" --token pa_…
+```
+
+Or use any harness directly — just set the env and the proxy does the rest:
+```bash
+export ANTHROPIC_BASE_URL=https://proxy.you.com/anthropic
+export ANTHROPIC_API_KEY=pa_…          # the machine token, not the real key
+claude -p "ship it"
+```
+
+## The dashboard
+`proxyagent serve` ships a dashboard at `/` — mint/revoke tokens, watch live usage and a
+full request audit log, see configured providers + proxied tools. Paste the admin token to
+open it.
+
+## Proxied tools — the same trick, for tools
+The proxy can also hold your **tool** keys and hand agents governed tools — so an agent gets
+web search (and custom tools) without ever holding the tool's credential.
+
+```bash
+export TAVILY_API_KEY=tvly-…                                   # web_search uses this; agents never see it
+export PROXYAGENT_TOOLS='[{"name":"crm","url":"https://hooks.you.com/crm","headers":{"Authorization":"Bearer …"}}]'
+# then send requests with header  x-proxyagent-tools: on  → tool defs are injected;
+# the proxy executes calls to managed tools server-side (keys stay here).
+```
+
+## Security model
+- **Real keys never leave the proxy** — read from env, never persisted, never logged, never returned.
+- **Machine tokens are stored hashed** (SHA-256); plaintext shown once. A stolen DB yields nothing usable.
+- **Scoped** (`provider:model` globs), **expiring** (TTL), **revocable**, **rate-limited**.
+- **Constant-time** token comparison; sensitive headers redacted from logs.
+- Admin API + dashboard gated by a separate admin token. Run it behind TLS.
+
+## SDK
+```python
+import proxyagent
+
+# host the proxy (embed in your own service):
+app = proxyagent.create_app()              # ASGI app
+
+# mint tokens programmatically:
+admin = proxyagent.Admin("https://proxy.you.com", "pa_admin_…")
+token = admin.mint("ci-runner", scope=["anthropic:claude-*"], ttl_seconds=3600)
+
+# run a harness on this machine, no key here:
+proxyagent.run("claude-code", goal="build the app",
+               proxy="https://proxy.you.com", token=token)
+```
+
+## Supported harnesses
+`claude-code`, `codex`, and any **custom** command (`--command "my-agent {goal}"`). Adding one
+is a few lines — it just needs to respect `*_BASE_URL`.
+
+## License
+Apache-2.0

proxyagent-0.1.0/proxyagent/__init__.py

@@ -0,0 +1,65 @@
+"""proxyagent — run any agent (Claude, Codex, custom) on any machine, with no API
+key on the machine. A secure, self-hosted proxy for models *and* tools.
+
+    # on the proxy host (holds the real keys):
+    import proxyagent
+    proxyagent.serve()                       # or: $ proxyagent serve
+
+    # on any remote machine (holds only a throwaway token):
+    proxyagent.run("claude-code", goal="build the app",
+                   proxy="https://proxy.you.com", token="pa_…")
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .harness import run  # noqa: F401  (the headline SDK call)
+
+__version__ = "0.1.0"
+__all__ = ["run", "serve", "create_app", "Config", "Admin", "__version__"]
+
+
+def create_app(config=None):
+    """The ASGI app, for embedding behind your own server."""
+    from .server import create_app as _c
+    return _c(config)
+
+
+def serve(host: str = "127.0.0.1", port: int = 8080, config=None):
+    """Run the proxy + dashboard."""
+    import uvicorn
+    from .config import Config
+    cfg = config or Config.load()
+    uvicorn.run(create_app(cfg), host=host, port=port, log_level="warning")
+
+
+def Config():  # noqa: N802 — convenience re-export
+    from .config import Config as _C
+    return _C.load()
+
+
+class Admin:
+    """Programmatic admin client — mint/list/revoke tokens against a running proxy."""
+
+    def __init__(self, proxy: str, admin_token: str):
+        import httpx
+        self._c = httpx.Client(base_url=proxy.rstrip("/"),
+                               headers={"x-admin-token": admin_token}, timeout=30)
+
+    def mint(self, label: str = "machine", scope: Optional[list] = None,
+             ttl_seconds: Optional[int] = None, rate_limit: int = 0) -> str:
+        r = self._c.post("/admin/tokens", json={
+            "label": label, "scope": scope or ["*"], "ttl_seconds": ttl_seconds,
+            "rate_limit": rate_limit})
+        r.raise_for_status()
+        return r.json()["token"]
+
+    def tokens(self) -> list:
+        return self._c.get("/admin/tokens").json()["tokens"]
+
+    def revoke(self, token_id: str) -> None:
+        self._c.delete(f"/admin/tokens/{token_id}").raise_for_status()
+
+    def logs(self, limit: int = 100) -> list:
+        return self._c.get("/admin/logs", params={"limit": limit}).json()["logs"]

proxyagent-0.1.0/proxyagent/cli.py

@@ -0,0 +1,145 @@
+"""proxyagent CLI — serve the proxy, mint tokens, run harnesses, watch usage."""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+import httpx
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+app = typer.Typer(help="Run any agent on any machine — with no API key on the machine.", no_args_is_help=True)
+console = Console()
+err = Console(stderr=True)
+
+
+def _admin_client(proxy: str, admin: Optional[str]) -> httpx.Client:
+    admin = admin or os.environ.get("PROXYAGENT_ADMIN_TOKEN")
+    if not admin:
+        err.print("[red]Need an admin token[/red] (--admin or PROXYAGENT_ADMIN_TOKEN). "
+                  "It's printed when you run [bold]proxyagent serve[/bold].")
+        raise typer.Exit(1)
+    return httpx.Client(base_url=proxy.rstrip("/"), headers={"x-admin-token": admin}, timeout=30)
+
+
+@app.command()
+def serve(host: str = "127.0.0.1", port: int = 8080):
+    """Run the proxy server + dashboard."""
+    import uvicorn
+
+    from .config import Config
+    from .server import create_app
+
+    config = Config.load()
+    if config.admin_token_plain:
+        console.print(Panel.fit(
+            f"[green]✓ proxyagent[/green]\n\n[bold]Admin token[/bold] (shown once)\n"
+            f"  [yellow]{config.admin_token_plain}[/yellow]\n\n"
+            f"[dim]Save it — you need it for the dashboard + `proxyagent token`.[/dim]",
+            border_style="green"))
+    console.print(f"[dim]Dashboard:[/dim] http://{host}:{port}   "
+                  f"[dim]providers:[/dim] {', '.join(config.configured_providers()) or 'none — set ANTHROPIC_API_KEY / OPENAI_API_KEY'}")
+    uvicorn.run(create_app(config), host=host, port=port, log_level="warning")
+
+
+@app.command("run")
+def run_harness(
+    harness: str = typer.Argument(..., help="claude-code | codex | <custom>"),
+    goal: str = typer.Option(..., "--goal", "-g", help="What the agent should do."),
+    proxy: str = typer.Option("http://127.0.0.1:8080", "--proxy"),
+    token: Optional[str] = typer.Option(None, "--token", help="Machine token (or PROXYAGENT_TOKEN)."),
+    command: Optional[str] = typer.Option(None, "--command", help="Custom harness command template."),
+    cwd: Optional[str] = typer.Option(None, "--cwd"),
+):
+    """Run a harness on THIS machine, pointed at the proxy (no real key needed here)."""
+    from . import harness as H
+
+    tok = token or os.environ.get("PROXYAGENT_TOKEN")
+    if not tok:
+        err.print("[red]Need a machine token[/red] (--token or PROXYAGENT_TOKEN).")
+        raise typer.Exit(1)
+    console.print(f"[dim]→ {harness} via {proxy} (no key on this machine)[/dim]")
+    code = H.run(harness, goal, proxy_url=proxy, token=tok, cwd=cwd, command=command)
+    raise typer.Exit(code)
+
+
+token_app = typer.Typer(help="Mint / list / revoke machine tokens.")
+app.add_typer(token_app, name="token")
+
+
+@token_app.command("new")
+def token_new(
+    label: str = typer.Argument("machine"),
+    scope: list[str] = typer.Option(["*"], "--scope", help="Allowed provider:model globs, e.g. anthropic:claude-*"),
+    ttl: Optional[int] = typer.Option(None, "--ttl", help="Seconds until expiry."),
+    rate: int = typer.Option(0, "--rate", help="Max requests/min (0 = unlimited)."),
+    proxy: str = typer.Option("http://127.0.0.1:8080", "--proxy"),
+    admin: Optional[str] = typer.Option(None, "--admin"),
+):
+    """Mint a machine token — give it to a remote machine; it holds no real key."""
+    with _admin_client(proxy, admin) as c:
+        r = c.post("/admin/tokens", json={"label": label, "scope": list(scope),
+                                          "ttl_seconds": ttl, "rate_limit": rate})
+    if r.status_code >= 400:
+        err.print(f"[red]✗[/red] {r.text}"); raise typer.Exit(1)
+    d = r.json()
+    console.print(Panel.fit(
+        f"[green]✓ machine token[/green] [dim]({label})[/dim]\n\n  [yellow]{d['token']}[/yellow]\n\n"
+        f"[dim]scope: {', '.join(scope)} · shown once[/dim]", border_style="green"))
+
+
+@token_app.command("ls")
+def token_ls(proxy: str = typer.Option("http://127.0.0.1:8080", "--proxy"),
+             admin: Optional[str] = typer.Option(None, "--admin")):
+    """List machine tokens."""
+    with _admin_client(proxy, admin) as c:
+        r = c.get("/admin/tokens")
+    if r.status_code >= 400:
+        err.print(f"[red]✗[/red] {r.text}"); raise typer.Exit(1)
+    rows = r.json()["tokens"]
+    if not rows:
+        console.print("[dim]No tokens.[/dim]"); return
+    t = Table(title="Machine tokens")
+    for col in ("ID", "Label", "Token", "Scope", "Status"):
+        t.add_column(col)
+    for k in rows:
+        t.add_row(k["id"], k["label"], k["masked"], ", ".join(k["scope"]),
+                  "[red]revoked[/red]" if k["revoked"] else "[green]active[/green]")
+    console.print(t)
+
+
+@token_app.command("revoke")
+def token_revoke(token_id: str, proxy: str = typer.Option("http://127.0.0.1:8080", "--proxy"),
+                 admin: Optional[str] = typer.Option(None, "--admin")):
+    """Revoke a token by id."""
+    with _admin_client(proxy, admin) as c:
+        r = c.delete(f"/admin/tokens/{token_id}")
+    if r.status_code >= 400:
+        err.print(f"[red]✗[/red] {r.text}"); raise typer.Exit(1)
+    console.print(f"[green]✓[/green] revoked {token_id}")
+
+
+@app.command()
+def logs(limit: int = 50, proxy: str = typer.Option("http://127.0.0.1:8080", "--proxy"),
+         admin: Optional[str] = typer.Option(None, "--admin")):
+    """Recent proxied requests (audit log)."""
+    with _admin_client(proxy, admin) as c:
+        r = c.get("/admin/logs", params={"limit": limit})
+    if r.status_code >= 400:
+        err.print(f"[red]✗[/red] {r.text}"); raise typer.Exit(1)
+    rows = r.json()["logs"]
+    t = Table(title="Requests")
+    for col in ("Token", "Provider", "Model", "Status", "In", "Out", "ms"):
+        t.add_column(col)
+    for g in rows:
+        t.add_row(g.get("token_label") or "", g.get("provider") or "", (g.get("model") or "")[:28],
+                  str(g.get("status") or ""), str(g.get("prompt_tokens") or "-"),
+                  str(g.get("completion_tokens") or "-"), str(g.get("latency_ms") or ""))
+    console.print(t)
+
+
+if __name__ == "__main__":
+    app()

proxyagent-0.1.0/proxyagent/config.py

@@ -0,0 +1,82 @@
+"""Configuration — provider upstreams, real credentials (env only), paths, admin auth.
+
+Real keys are read from the environment and never persisted. The proxy is the ONLY
+place they live.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .security import hash_token, new_token, ADMIN_PREFIX
+
+HOME = Path(os.environ.get("PROXYAGENT_HOME", Path.home() / ".proxyagent"))
+
+
+@dataclass
+class Provider:
+    name: str
+    base_url: str          # upstream API root
+    key_env: str           # env var holding the REAL key
+    auth_style: str        # "bearer" (OpenAI) | "x-api-key" (Anthropic)
+    extra_headers: dict = field(default_factory=dict)
+
+    @property
+    def key(self) -> str | None:
+        return os.environ.get(self.key_env)
+
+    def auth_headers(self) -> dict:
+        key = self.key
+        if not key:
+            return {}
+        if self.auth_style == "x-api-key":
+            return {"x-api-key": key, **self.extra_headers}
+        return {"Authorization": f"Bearer {key}", **self.extra_headers}
+
+
+# Built-in upstreams. base_url overridable via env (e.g. Azure, self-hosted, gateways).
+def _provider(name, default_base, key_env, style, extra=None) -> Provider:
+    base = os.environ.get(f"PROXYAGENT_{name.upper()}_BASE_URL", default_base)
+    return Provider(name, base.rstrip("/"), key_env, style, extra or {})
+
+
+PROVIDERS: dict[str, Provider] = {
+    "anthropic": _provider(
+        "anthropic", "https://api.anthropic.com", "ANTHROPIC_API_KEY", "x-api-key",
+        {"anthropic-version": os.environ.get("ANTHROPIC_VERSION", "2023-06-01")},
+    ),
+    "openai": _provider("openai", "https://api.openai.com", "OPENAI_API_KEY", "bearer"),
+}
+
+
+@dataclass
+class Config:
+    home: Path = HOME
+    db_path: str = ""
+    admin_token_hash: str = ""
+    admin_token_plain: str | None = None   # only set when freshly generated
+    request_timeout: float = 600.0
+
+    @classmethod
+    def load(cls) -> "Config":
+        HOME.mkdir(parents=True, exist_ok=True)
+        cfg = cls(db_path=str(HOME / "proxyagent.db"))
+        # Admin token: from env, or a persisted one, or freshly generated (shown once).
+        env_admin = os.environ.get("PROXYAGENT_ADMIN_TOKEN")
+        admin_file = HOME / "admin_token"
+        if env_admin:
+            cfg.admin_token_hash = hash_token(env_admin)
+        elif admin_file.exists():
+            cfg.admin_token_hash = admin_file.read_text().strip()
+        else:
+            plain = new_token(ADMIN_PREFIX)
+            cfg.admin_token_hash = hash_token(plain)
+            admin_file.write_text(cfg.admin_token_hash)
+            admin_file.chmod(0o600)
+            cfg.admin_token_plain = plain
+        return cfg
+
+    def configured_providers(self) -> list[str]:
+        return [n for n, p in PROVIDERS.items() if p.key]

proxyagent-0.1.0/proxyagent/harness.py

@@ -0,0 +1,73 @@
+"""Run an agent harness on a machine, pointed at the proxy — so the machine holds
+only the throwaway proxy token, never a real key.
+
+Almost every harness honours `*_BASE_URL`, so the shim is tiny: set the base URL to
+the proxy, set the "api key" to the machine token, and launch the harness unmodified.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import subprocess
+from dataclasses import dataclass, field
+from typing import Callable
+
+
+@dataclass
+class Harness:
+    name: str
+    # build argv from a goal (headless / non-interactive invocation)
+    launch: Callable[[str], list[str]]
+    check: list[str] = field(default_factory=list)     # how to detect it's installed
+    install_hint: str = ""
+
+    def env(self, proxy_url: str, token: str) -> dict:
+        base = proxy_url.rstrip("/")
+        return {
+            "ANTHROPIC_BASE_URL": f"{base}/anthropic",
+            "ANTHROPIC_API_KEY": token,
+            "OPENAI_BASE_URL": f"{base}/openai/v1",
+            "OPENAI_API_BASE": f"{base}/openai/v1",
+            "OPENAI_API_KEY": token,
+        }
+
+
+HARNESSES: dict[str, Harness] = {
+    "claude-code": Harness(
+        name="claude-code",
+        launch=lambda goal: ["claude", "-p", goal, "--permission-mode", "bypassPermissions"],
+        check=["claude", "--version"],
+        install_hint="npm i -g @anthropic-ai/claude-code",
+    ),
+    "codex": Harness(
+        name="codex",
+        launch=lambda goal: ["codex", "exec", goal],
+        check=["codex", "--version"],
+        install_hint="npm i -g @openai/codex",
+    ),
+}
+
+
+def register_custom(name: str, command: str) -> Harness:
+    """A custom harness: `command` is a template; {goal} is substituted."""
+    def _launch(goal: str) -> list[str]:
+        return shlex.split(command.replace("{goal}", goal)) if "{goal}" in command \
+            else shlex.split(command) + [goal]
+    h = Harness(name=name, launch=_launch)
+    HARNESSES[name] = h
+    return h
+
+
+def run(harness: str, goal: str, *, proxy_url: str, token: str,
+        cwd: str | None = None, extra_env: dict | None = None,
+        command: str | None = None) -> int:
+    """Run a harness against a goal, pointed at the proxy. Streams to stdout.
+    Returns the exit code."""
+    h = HARNESSES.get(harness) or (register_custom(harness, command) if command else None)
+    if h is None:
+        raise ValueError(f"unknown harness {harness!r} (pass command=... for a custom one)")
+    env = {**os.environ, **h.env(proxy_url, token), **(extra_env or {})}
+    argv = h.launch(goal)
+    proc = subprocess.run(argv, cwd=cwd, env=env)
+    return proc.returncode