proxyagent 0.1.0__py3-none-any.whl

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/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/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/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

proxyagent/providers.py

@@ -0,0 +1,98 @@
+"""Upstream forwarding + scope enforcement.
+
+The proxy receives a request authed by a machine token, swaps in the REAL provider
+key, and forwards it upstream — streaming straight through. The machine never sees
+the real key; the proxy logs usage for every call.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import json
+
+import httpx
+
+from .config import Config, PROVIDERS
+from .store import Store, now_ms
+
+# Map our public path → (provider, upstream path).
+ROUTES = {
+    "anthropic": ("anthropic", "/v1/messages"),
+    "openai": ("openai", "/v1/chat/completions"),
+}
+
+
+def scope_allows(scope: list[str], provider: str, model: str) -> bool:
+    """A scope entry is a glob over 'provider:model', e.g. 'anthropic:claude-*', or '*'."""
+    target = f"{provider}:{model or '*'}"
+    for entry in scope:
+        if entry == "*" or fnmatch.fnmatch(target, entry) or fnmatch.fnmatch(provider, entry):
+            return True
+    return False
+
+
+def _extract_usage(provider: str, payload: dict) -> tuple[int | None, int | None]:
+    u = payload.get("usage") or {}
+    if provider == "anthropic":
+        return u.get("input_tokens"), u.get("output_tokens")
+    return u.get("prompt_tokens"), u.get("completion_tokens")
+
+
+async def forward(
+    config: Config, provider_name: str, upstream_path: str, body: dict,
+    *, streaming: bool, token: dict, store: Store, tools_used: list[str] | None = None,
+):
+    """Forward a request upstream. Returns (status, headers, body_iter_or_dict, log_after)."""
+    provider = PROVIDERS[provider_name]
+    if not provider.key:
+        return 502, {}, {"error": f"provider '{provider_name}' not configured on the proxy"}, None
+
+    url = provider.base_url + upstream_path
+    headers = {"content-type": "application/json", **provider.auth_headers()}
+    model = body.get("model", "")
+    t0 = now_ms()
+
+    def _log(status, ptok, ctok, err=None):
+        store.log_request(
+            token_id=token["id"], token_label=token.get("label"), provider=provider_name,
+            model=model, status=status, prompt_tokens=ptok, completion_tokens=ctok,
+            latency_ms=now_ms() - t0, streamed=1 if streaming else 0,
+            tools_used=json.dumps(tools_used or []), error=err,
+        )
+
+    if streaming:
+        async def _gen():
+            ptok = ctok = None
+            status = 200
+            try:
+                async with httpx.AsyncClient(timeout=config.request_timeout) as client:
+                    async with client.stream("POST", url, headers=headers, json=body) as resp:
+                        status = resp.status_code
+                        async for chunk in resp.aiter_raw():
+                            # Best-effort usage capture from the final SSE event.
+                            text = chunk.decode("utf-8", "ignore")
+                            if '"output_tokens"' in text or '"completion_tokens"' in text:
+                                try:
+                                    for line in text.splitlines():
+                                        if line.startswith("data:"):
+                                            d = json.loads(line[5:].strip())
+                                            usage = d.get("usage") or (d.get("message") or {}).get("usage") or {}
+                                            ptok = usage.get("input_tokens") or usage.get("prompt_tokens") or ptok
+                                            ctok = usage.get("output_tokens") or usage.get("completion_tokens") or ctok
+                                except Exception:
+                                    pass
+                            yield chunk
+            finally:
+                _log(status, ptok, ctok)
+        return 200, {"content-type": "text/event-stream"}, _gen(), None
+
+    # Non-streaming.
+    async with httpx.AsyncClient(timeout=config.request_timeout) as client:
+        resp = await client.post(url, headers=headers, json=body)
+    try:
+        payload = resp.json()
+    except Exception:
+        payload = {"error": resp.text}
+    ptok, ctok = _extract_usage(provider_name, payload if isinstance(payload, dict) else {})
+    _log(resp.status_code, ptok, ctok, None if resp.is_success else str(payload)[:300])
+    return resp.status_code, {"content-type": "application/json"}, payload, None

proxyagent/security.py

@@ -0,0 +1,59 @@
+"""Security primitives — token minting, hashing, constant-time checks, redaction.
+
+Design rules (the whole point of this project):
+  * Real provider/tool keys live ONLY on the server, in memory/config — never in the
+    DB, never in logs, never returned over the API.
+  * Machine tokens are stored as salted SHA-256 hashes. The plaintext is shown ONCE,
+    at creation. A leaked DB reveals no usable token.
+  * All token comparisons are constant-time.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+
+TOKEN_PREFIX = "pa_"
+ADMIN_PREFIX = "pa_admin_"
+
+
+def new_token(prefix: str = TOKEN_PREFIX, *, nbytes: int = 32) -> str:
+    """A high-entropy, URL-safe token. Shown to the caller exactly once."""
+    return prefix + secrets.token_urlsafe(nbytes)
+
+
+def hash_token(token: str) -> str:
+    """Stable SHA-256 hex of a token — what we persist + compare against."""
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+def token_matches(token: str, stored_hash: str) -> bool:
+    """Constant-time check of a presented token against a stored hash."""
+    return hmac.compare_digest(hash_token(token), stored_hash)
+
+
+def constant_time_eq(a: str, b: str) -> bool:
+    return hmac.compare_digest(a.encode("utf-8"), b.encode("utf-8"))
+
+
+# ------------------------------------------------------------------ #
+# Redaction — so secrets never reach logs or error bodies.
+# ------------------------------------------------------------------ #
+
+_SENSITIVE_HEADERS = {"authorization", "x-api-key", "api-key", "proxy-authorization"}
+
+
+def redact_headers(headers: dict) -> dict:
+    out = {}
+    for k, v in headers.items():
+        out[k] = "***" if k.lower() in _SENSITIVE_HEADERS else v
+    return out
+
+
+def mask(value: str | None, keep: int = 4) -> str:
+    """Mask a secret for display: pa_abcd… → pa_abcd…(masked)."""
+    if not value:
+        return ""
+    head = value[: keep + len(TOKEN_PREFIX)] if value.startswith(TOKEN_PREFIX) else value[:keep]
+    return f"{head}…"

proxyagent/server.py

@@ -0,0 +1,186 @@
+"""The proxy server — FastAPI.
+
+Public (machine-token) endpoints mirror the provider APIs so harnesses just point
+their base URL here. Admin endpoints (admin-token) manage tokens, view usage/logs,
+and list tools. The static dashboard is served at /.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from fastapi import FastAPI, Header, HTTPException, Request
+from fastapi.responses import HTMLResponse, JSONResponse, StreamingResponse
+from pydantic import BaseModel
+
+from .config import Config, PROVIDERS
+from .providers import ROUTES, forward, scope_allows
+from .security import token_matches
+from .store import Store, now_ms
+from .tools import ToolRegistry
+
+UI_DIR = Path(__file__).resolve().parent / "ui"
+
+
+class TokenBody(BaseModel):
+    label: str = "machine"
+    scope: list[str] = ["*"]
+    ttl_seconds: int | None = None
+    rate_limit: int = 0
+
+
+def create_app(config: Config | None = None) -> FastAPI:
+    config = config or Config.load()
+    store = Store(config.db_path)
+    tools = ToolRegistry(config)
+    app = FastAPI(title="proxyagent", version="0.1.0")
+    app.state.store = store
+
+    # ------------------------------------------------------------------ #
+    # Auth helpers
+    # ------------------------------------------------------------------ #
+    def _bearer(authorization: str | None, x_api_key: str | None) -> str | None:
+        if authorization and authorization.lower().startswith("bearer "):
+            return authorization[7:].strip()
+        return x_api_key
+
+    def auth_machine(authorization, x_api_key) -> dict:
+        from .security import hash_token
+        tok = _bearer(authorization, x_api_key)
+        if not tok:
+            raise HTTPException(401, "missing token")
+        row = store.get_token_by_hash(hash_token(tok))
+        if not row or row["revoked"]:
+            raise HTTPException(401, "invalid or revoked token")
+        if row["expires_ms"] and row["expires_ms"] < now_ms():
+            raise HTTPException(401, "token expired")
+        if row["rate_limit"] and store.recent_request_count(row["id"]) >= row["rate_limit"]:
+            raise HTTPException(429, "rate limit exceeded")
+        store.touch_token(row["id"])
+        return row
+
+    def require_admin(authorization, x_admin_token) -> None:
+        tok = None
+        if authorization and authorization.lower().startswith("bearer "):
+            tok = authorization[7:].strip()
+        tok = tok or x_admin_token
+        if not tok or not token_matches(tok, config.admin_token_hash):
+            raise HTTPException(401, "admin auth required")
+
+    import json as _json
+    from .store import Store as _S  # noqa
+
+    # ------------------------------------------------------------------ #
+    # Provider proxy endpoints
+    # ------------------------------------------------------------------ #
+    async def _proxy(provider_key: str, request: Request, authorization, x_api_key):
+        token = auth_machine(authorization, x_api_key)
+        provider_name, upstream_path = ROUTES[provider_key]
+        body = await request.json()
+        model = body.get("model", "")
+        scope = _json.loads(token["scope_json"])
+        if not scope_allows(scope, provider_name, model):
+            raise HTTPException(403, f"token scope does not allow {provider_name}:{model}")
+
+        used_tools: list[str] = []
+        if request.headers.get("x-proxyagent-tools", "").lower() in ("1", "on", "true"):
+            body = tools.inject(body, provider_name)
+            used_tools = tools.names()
+
+        streaming = bool(body.get("stream"))
+        status, headers, payload, _ = await forward(
+            config, provider_name, upstream_path, body,
+            streaming=streaming, token=token, store=store, tools_used=used_tools,
+        )
+        if streaming:
+            return StreamingResponse(payload, media_type="text/event-stream")
+        return JSONResponse(payload, status_code=status)
+
+    @app.post("/anthropic/v1/messages")
+    async def anthropic(request: Request, authorization: str | None = Header(None),
+                        x_api_key: str | None = Header(None)):
+        return await _proxy("anthropic", request, authorization, x_api_key)
+
+    @app.post("/openai/v1/chat/completions")
+    async def openai(request: Request, authorization: str | None = Header(None),
+                     x_api_key: str | None = Header(None)):
+        return await _proxy("openai", request, authorization, x_api_key)
+
+    # ------------------------------------------------------------------ #
+    # Tools — execute a proxied tool (creds stay here)
+    # ------------------------------------------------------------------ #
+    @app.get("/v1/tools")
+    async def list_tools(authorization: str | None = Header(None),
+                         x_api_key: str | None = Header(None)):
+        auth_machine(authorization, x_api_key)
+        return {"tools": tools.list()}
+
+    @app.post("/v1/tools/{name}/execute")
+    async def exec_tool(name: str, request: Request, authorization: str | None = Header(None),
+                        x_api_key: str | None = Header(None)):
+        auth_machine(authorization, x_api_key)
+        args = await request.json()
+        if not tools.manages(name):
+            raise HTTPException(404, f"unknown tool '{name}'")
+        return {"result": await tools.execute(name, args)}
+
+    # ------------------------------------------------------------------ #
+    # Admin API
+    # ------------------------------------------------------------------ #
+    @app.post("/admin/tokens")
+    async def create_token(body: TokenBody, authorization: str | None = Header(None),
+                           x_admin_token: str | None = Header(None)):
+        require_admin(authorization, x_admin_token)
+        plain, row = store.create_token(body.label, body.scope,
+                                        ttl_seconds=body.ttl_seconds, rate_limit=body.rate_limit)
+        return {"token": plain, "id": row["id"], "label": row["label"],
+                "scope": body.scope, "note": "shown once — store it now"}
+
+    @app.get("/admin/tokens")
+    async def list_tokens_ep(authorization: str | None = Header(None),
+                             x_admin_token: str | None = Header(None)):
+        require_admin(authorization, x_admin_token)
+        out = []
+        for t in store.list_tokens():
+            out.append({"id": t["id"], "label": t["label"], "masked": t["masked"],
+                        "scope": _json.loads(t["scope_json"]), "revoked": bool(t["revoked"]),
+                        "rate_limit": t["rate_limit"], "expires_ms": t["expires_ms"],
+                        "last_used_ms": t["last_used_ms"]})
+        return {"tokens": out}
+
+    @app.delete("/admin/tokens/{tid}")
+    async def revoke_token_ep(tid: str, authorization: str | None = Header(None),
+                              x_admin_token: str | None = Header(None)):
+        require_admin(authorization, x_admin_token)
+        if not store.revoke_token(tid):
+            raise HTTPException(404, "no such token")
+        return {"ok": True}
+
+    @app.get("/admin/logs")
+    async def logs_ep(limit: int = 200, authorization: str | None = Header(None),
+                      x_admin_token: str | None = Header(None)):
+        require_admin(authorization, x_admin_token)
+        return {"logs": store.list_logs(limit)}
+
+    @app.get("/admin/usage")
+    async def usage_ep(authorization: str | None = Header(None),
+                       x_admin_token: str | None = Header(None)):
+        require_admin(authorization, x_admin_token)
+        return {"usage": store.usage_summary(),
+                "providers": config.configured_providers(),
+                "tools": tools.list()}
+
+    @app.get("/healthz")
+    async def healthz():
+        return {"ok": True, "providers": config.configured_providers(), "tools": tools.names()}
+
+    # ------------------------------------------------------------------ #
+    # Dashboard
+    # ------------------------------------------------------------------ #
+    @app.get("/", response_class=HTMLResponse)
+    async def ui():
+        idx = UI_DIR / "index.html"
+        return HTMLResponse(idx.read_text() if idx.exists() else "<h1>proxyagent</h1>")
+
+    return app

proxyagent/store.py

@@ -0,0 +1,148 @@
+"""Persistence — machine tokens (hashed) + a full request/usage audit log.
+
+SQLite, guarded by a lock so it's safe across the server's worker threads.
+"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import threading
+import time
+import uuid
+from pathlib import Path
+
+from .security import hash_token, new_token, mask
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS tokens (
+    id          TEXT PRIMARY KEY,
+    hash        TEXT NOT NULL UNIQUE,
+    label       TEXT,
+    scope_json  TEXT NOT NULL DEFAULT '["*"]',   -- allowed "provider:model" globs
+    rate_limit  INTEGER NOT NULL DEFAULT 0,       -- max requests/min (0 = unlimited)
+    created_ms  INTEGER,
+    expires_ms  INTEGER,                          -- NULL = never
+    revoked     INTEGER NOT NULL DEFAULT 0,
+    last_used_ms INTEGER,
+    masked      TEXT
+);
+CREATE TABLE IF NOT EXISTS logs (
+    id           TEXT PRIMARY KEY,
+    ts_ms        INTEGER,
+    token_id     TEXT,
+    token_label  TEXT,
+    provider     TEXT,
+    model        TEXT,
+    status       INTEGER,
+    prompt_tokens     INTEGER,
+    completion_tokens INTEGER,
+    latency_ms   INTEGER,
+    streamed     INTEGER,
+    tools_used   TEXT,
+    error        TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_logs_ts ON logs (ts_ms DESC);
+CREATE INDEX IF NOT EXISTS idx_logs_token ON logs (token_id);
+"""
+
+
+def now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+class Store:
+    def __init__(self, path: str | Path = ":memory:"):
+        self._lock = threading.RLock()
+        self._conn = sqlite3.connect(str(path), check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.executescript(_SCHEMA)
+        self._conn.commit()
+
+    # -- tokens ------------------------------------------------------------ #
+
+    def create_token(self, label: str, scope: list[str], *, ttl_seconds: int | None = None,
+                     rate_limit: int = 0) -> tuple[str, dict]:
+        """Mint a token. Returns (plaintext_once, row). Plaintext is never stored."""
+        plain = new_token()
+        tid = "tok_" + uuid.uuid4().hex[:12]
+        expires = now_ms() + ttl_seconds * 1000 if ttl_seconds else None
+        with self._lock:
+            self._conn.execute(
+                """INSERT INTO tokens (id, hash, label, scope_json, rate_limit, created_ms,
+                                       expires_ms, masked)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+                (tid, hash_token(plain), label, json.dumps(scope), rate_limit, now_ms(),
+                 expires, mask(plain)),
+            )
+            self._conn.commit()
+        return plain, self.get_token(tid)
+
+    def get_token(self, tid: str) -> dict | None:
+        with self._lock:
+            r = self._conn.execute("SELECT * FROM tokens WHERE id=?", (tid,)).fetchone()
+        return dict(r) if r else None
+
+    def get_token_by_hash(self, h: str) -> dict | None:
+        with self._lock:
+            r = self._conn.execute("SELECT * FROM tokens WHERE hash=?", (h,)).fetchone()
+        return dict(r) if r else None
+
+    def list_tokens(self) -> list[dict]:
+        with self._lock:
+            rows = self._conn.execute("SELECT * FROM tokens ORDER BY created_ms DESC").fetchall()
+        return [dict(r) for r in rows]
+
+    def revoke_token(self, tid: str) -> bool:
+        with self._lock:
+            cur = self._conn.execute("UPDATE tokens SET revoked=1 WHERE id=?", (tid,))
+            self._conn.commit()
+        return cur.rowcount > 0
+
+    def touch_token(self, tid: str) -> None:
+        with self._lock:
+            self._conn.execute("UPDATE tokens SET last_used_ms=? WHERE id=?", (now_ms(), tid))
+            self._conn.commit()
+
+    def recent_request_count(self, tid: str, window_ms: int = 60_000) -> int:
+        with self._lock:
+            r = self._conn.execute(
+                "SELECT COUNT(*) c FROM logs WHERE token_id=? AND ts_ms>=?",
+                (tid, now_ms() - window_ms),
+            ).fetchone()
+        return r["c"]
+
+    # -- logs / usage ------------------------------------------------------ #
+
+    def log_request(self, **kw) -> None:
+        kw.setdefault("id", "log_" + uuid.uuid4().hex[:12])
+        kw.setdefault("ts_ms", now_ms())
+        cols = ["id", "ts_ms", "token_id", "token_label", "provider", "model", "status",
+                "prompt_tokens", "completion_tokens", "latency_ms", "streamed", "tools_used", "error"]
+        vals = [kw.get(c) for c in cols]
+        with self._lock:
+            self._conn.execute(
+                f"INSERT INTO logs ({','.join(cols)}) VALUES ({','.join('?' * len(cols))})", vals
+            )
+            self._conn.commit()
+
+    def list_logs(self, limit: int = 200) -> list[dict]:
+        with self._lock:
+            rows = self._conn.execute(
+                "SELECT * FROM logs ORDER BY ts_ms DESC LIMIT ?", (limit,)
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    def usage_summary(self) -> dict:
+        with self._lock:
+            r = self._conn.execute(
+                """SELECT COUNT(*) requests,
+                          COALESCE(SUM(prompt_tokens),0) prompt_tokens,
+                          COALESCE(SUM(completion_tokens),0) completion_tokens
+                   FROM logs"""
+            ).fetchone()
+        return dict(r)
+
+    def close(self) -> None:
+        with self._lock:
+            self._conn.close()

proxyagent/tools.py

@@ -0,0 +1,144 @@
+"""Proxied tools — give agents governed tools (web search, custom HTTP tools) whose
+credentials live ONLY on the proxy.
+
+The proxy can:
+  * inject tool definitions into a model request (so the agent can call them), and
+  * execute the tool server-side when the model asks for it — so the agent never
+    holds the tool's API key (same security model as the model keys).
+
+Built-in: `web_search`. Custom tools are registered as HTTP webhooks in config; their
+auth headers stay on the proxy.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from typing import Awaitable, Callable
+
+import httpx
+
+
+@dataclass
+class Tool:
+    name: str
+    description: str
+    input_schema: dict                       # JSON Schema for the tool input
+    executor: Callable[[dict], Awaitable[str]]
+
+    def anthropic_def(self) -> dict:
+        return {"name": self.name, "description": self.description, "input_schema": self.input_schema}
+
+    def openai_def(self) -> dict:
+        return {"type": "function", "function": {
+            "name": self.name, "description": self.description, "parameters": self.input_schema}}
+
+
+# ------------------------------------------------------------------ #
+# Built-in: web search (Tavily if configured, else DuckDuckGo fallback).
+# The search key lives on the proxy — agents never see it.
+# ------------------------------------------------------------------ #
+
+async def _web_search(args: dict) -> str:
+    query = str(args.get("query", "")).strip()
+    if not query:
+        return "error: empty query"
+    tavily = os.environ.get("TAVILY_API_KEY")
+    try:
+        async with httpx.AsyncClient(timeout=20) as client:
+            if tavily:
+                r = await client.post("https://api.tavily.com/search", json={
+                    "api_key": tavily, "query": query, "max_results": 5})
+                data = r.json()
+                hits = [f"- {h['title']}: {h['url']}\n  {h.get('content','')[:300]}"
+                        for h in data.get("results", [])]
+                return ("\n".join(hits)) or "no results"
+            # Keyless fallback: DuckDuckGo Instant Answer.
+            r = await client.get("https://api.duckduckgo.com/", params={
+                "q": query, "format": "json", "no_html": 1})
+            data = r.json()
+            out = []
+            if data.get("AbstractText"):
+                out.append(data["AbstractText"])
+            for t in (data.get("RelatedTopics") or [])[:5]:
+                if isinstance(t, dict) and t.get("Text"):
+                    out.append(f"- {t['Text']} ({t.get('FirstURL','')})")
+            return "\n".join(out) or "no results (set TAVILY_API_KEY for full web search)"
+    except Exception as exc:  # noqa: BLE001
+        return f"search error: {exc}"
+
+
+WEB_SEARCH = Tool(
+    name="web_search",
+    description="Search the web and return the top results. Use for current info.",
+    input_schema={"type": "object", "properties": {
+        "query": {"type": "string", "description": "The search query"}}, "required": ["query"]},
+    executor=_web_search,
+)
+
+
+def _http_tool(spec: dict) -> Tool:
+    """A custom tool that POSTs the model's input to a URL you control. The tool's
+    auth headers live here on the proxy, not on the agent."""
+    url = spec["url"]
+    headers = spec.get("headers", {})
+
+    async def _run(args: dict) -> str:
+        async with httpx.AsyncClient(timeout=30) as client:
+            r = await client.post(url, headers=headers, json=args)
+        return r.text[:4000]
+
+    return Tool(spec["name"], spec.get("description", ""),
+                spec.get("input_schema", {"type": "object", "properties": {}}), _run)
+
+
+class ToolRegistry:
+    def __init__(self, config=None):
+        self._tools: dict[str, Tool] = {}
+        # web_search is on by default unless explicitly disabled.
+        if os.environ.get("PROXYAGENT_DISABLE_WEB_SEARCH") != "1":
+            self.register(WEB_SEARCH)
+        # Custom tools from PROXYAGENT_TOOLS (JSON list of {name,url,headers,...}).
+        raw = os.environ.get("PROXYAGENT_TOOLS")
+        if raw:
+            try:
+                for spec in json.loads(raw):
+                    self.register(_http_tool(spec))
+            except Exception:
+                pass
+
+    def register(self, tool: Tool) -> None:
+        self._tools[tool.name] = tool
+
+    def names(self) -> list[str]:
+        return list(self._tools)
+
+    def list(self) -> list[dict]:
+        return [{"name": t.name, "description": t.description} for t in self._tools.values()]
+
+    def inject(self, body: dict, provider: str) -> dict:
+        """Add registered tools to a request in the provider's format (non-destructive)."""
+        if not self._tools:
+            return body
+        existing = body.get("tools") or []
+        names = {self._tool_name(t, provider) for t in existing}
+        for t in self._tools.values():
+            d = t.anthropic_def() if provider == "anthropic" else t.openai_def()
+            if self._tool_name(d, provider) not in names:
+                existing.append(d)
+        body["tools"] = existing
+        return body
+
+    @staticmethod
+    def _tool_name(t: dict, provider: str) -> str:
+        return t.get("name") if provider == "anthropic" else (t.get("function") or {}).get("name", t.get("name"))
+
+    async def execute(self, name: str, args: dict) -> str:
+        tool = self._tools.get(name)
+        if not tool:
+            return f"error: unknown tool '{name}'"
+        return await tool.executor(args)
+
+    def manages(self, name: str) -> bool:
+        return name in self._tools

proxyagent/ui/index.html

@@ -0,0 +1,123 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>proxyagent</title>
+<style>
+  :root { --bg:#0b0c0e; --panel:#15171a; --line:#23262b; --txt:#e7e9ec; --dim:#8a9099; --grn:#34d39e; --red:#f87171; --yel:#fbbf24; }
+  * { box-sizing:border-box; } body { margin:0; background:var(--bg); color:var(--txt); font:14px/1.5 ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto; }
+  a { color:var(--grn); } code,.mono { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; }
+  header { display:flex; align-items:center; justify-content:space-between; padding:18px 28px; border-bottom:1px solid var(--line); }
+  .brand { display:flex; align-items:center; gap:10px; font-weight:600; font-size:16px; }
+  .dot { width:9px; height:9px; border-radius:50%; background:var(--grn); box-shadow:0 0 10px 1px rgba(52,211,158,.5); }
+  main { max-width:1100px; margin:0 auto; padding:28px; }
+  .grid { display:grid; grid-template-columns:repeat(auto-fit,minmax(180px,1fr)); gap:14px; margin-bottom:26px; }
+  .card { background:var(--panel); border:1px solid var(--line); border-radius:14px; padding:18px; }
+  .stat .n { font-size:30px; font-weight:600; } .stat .l { color:var(--dim); font-size:11px; text-transform:uppercase; letter-spacing:.08em; margin-top:4px; }
+  h2 { font-size:13px; text-transform:uppercase; letter-spacing:.08em; color:var(--dim); margin:26px 0 12px; }
+  table { width:100%; border-collapse:collapse; } th,td { text-align:left; padding:9px 10px; border-bottom:1px solid var(--line); font-size:13px; }
+  th { color:var(--dim); font-weight:500; font-size:11px; text-transform:uppercase; letter-spacing:.06em; }
+  input,button,select { font:inherit; border-radius:9px; border:1px solid var(--line); background:#0e1013; color:var(--txt); padding:8px 11px; }
+  button { background:var(--grn); color:#04130d; border:none; font-weight:600; cursor:pointer; } button.ghost { background:transparent; color:var(--dim); border:1px solid var(--line); }
+  button:hover { filter:brightness(1.08); } .row { display:flex; gap:9px; flex-wrap:wrap; align-items:center; }
+  .pill { padding:2px 9px; border-radius:99px; font-size:11px; } .pill.ok { background:rgba(52,211,158,.12); color:var(--grn); } .pill.no { background:rgba(248,113,113,.12); color:var(--red); }
+  .gate { max-width:420px; margin:90px auto; text-align:center; } .gate input { width:100%; margin:14px 0; }
+  .tok { background:#0e1013; border:1px dashed var(--grn); padding:12px; border-radius:10px; word-break:break-all; margin-top:12px; }
+  .hide { display:none; }
+</style>
+</head>
+<body>
+<div id="gate" class="gate">
+  <div class="brand" style="justify-content:center"><span class="dot"></span> proxyagent</div>
+  <p style="color:var(--dim)">Paste your admin token (printed by <code>proxyagent serve</code>).</p>
+  <input id="admintok" type="password" placeholder="pa_admin_…" />
+  <button onclick="saveAdmin()">Open dashboard</button>
+  <p id="gateerr" style="color:var(--red)"></p>
+</div>
+
+<div id="app" class="hide">
+  <header>
+    <div class="brand"><span class="dot"></span> proxyagent</div>
+    <div class="row"><span id="provs" style="color:var(--dim)"></span><button class="ghost" onclick="logout()">Sign out</button></div>
+  </header>
+  <main>
+    <div class="grid">
+      <div class="card stat"><div class="n" id="s_req">0</div><div class="l">Requests</div></div>
+      <div class="card stat"><div class="n" id="s_in">0</div><div class="l">Input tokens</div></div>
+      <div class="card stat"><div class="n" id="s_out">0</div><div class="l">Output tokens</div></div>
+      <div class="card stat"><div class="n" id="s_tools">0</div><div class="l">Proxied tools</div></div>
+    </div>
+
+    <h2>Mint a machine token</h2>
+    <div class="card">
+      <div class="row">
+        <input id="t_label" placeholder="label (e.g. macbook-01)" />
+        <input id="t_scope" placeholder="scope: * or anthropic:claude-*" style="flex:1" />
+        <input id="t_ttl" type="number" placeholder="ttl (s)" style="width:110px" />
+        <button onclick="mint()">Mint token</button>
+      </div>
+      <div id="minted" class="tok hide"></div>
+      <p style="color:var(--dim);margin:10px 0 0">The machine holds only this token — never a real key. Revoke anytime.</p>
+    </div>
+
+    <h2>Machine tokens</h2>
+    <div class="card"><table><thead><tr><th>ID</th><th>Label</th><th>Token</th><th>Scope</th><th>Status</th><th></th></tr></thead><tbody id="toks"></tbody></table></div>
+
+    <h2>Recent requests <span style="color:var(--dim);font-weight:400;text-transform:none;letter-spacing:0">· live</span></h2>
+    <div class="card"><table><thead><tr><th>Time</th><th>Token</th><th>Provider</th><th>Model</th><th>Status</th><th>In</th><th>Out</th><th>ms</th></tr></thead><tbody id="logs"></tbody></table></div>
+  </main>
+</div>
+
+<script>
+const A = () => localStorage.getItem("pa_admin");
+const H = () => ({ "x-admin-token": A(), "content-type": "application/json" });
+async function api(path, opts={}) { const r = await fetch(path, { ...opts, headers: { ...H(), ...(opts.headers||{}) } }); if (r.status===401) { logout(); throw new Error("unauthorized"); } return r; }
+
+function saveAdmin() { const v = document.getElementById("admintok").value.trim(); if (!v) return; localStorage.setItem("pa_admin", v); boot(); }
+function logout() { localStorage.removeItem("pa_admin"); document.getElementById("app").classList.add("hide"); document.getElementById("gate").classList.remove("hide"); }
+
+async function boot() {
+  try {
+    const u = await (await api("/admin/usage")).json();
+    document.getElementById("gate").classList.add("hide");
+    document.getElementById("app").classList.remove("hide");
+    document.getElementById("s_req").textContent = u.usage.requests;
+    document.getElementById("s_in").textContent = u.usage.prompt_tokens;
+    document.getElementById("s_out").textContent = u.usage.completion_tokens;
+    document.getElementById("s_tools").textContent = (u.tools||[]).length;
+    document.getElementById("provs").textContent = "providers: " + ((u.providers||[]).join(", ") || "none");
+    refreshTokens(); refreshLogs();
+  } catch (e) { document.getElementById("gateerr").textContent = "Invalid admin token."; }
+}
+
+async function refreshTokens() {
+  const d = await (await api("/admin/tokens")).json();
+  document.getElementById("toks").innerHTML = d.tokens.map(t => `
+    <tr><td class="mono">${t.id}</td><td>${t.label||""}</td><td class="mono">${t.masked||""}</td>
+    <td class="mono">${(t.scope||[]).join(", ")}</td>
+    <td>${t.revoked?'<span class="pill no">revoked</span>':'<span class="pill ok">active</span>'}</td>
+    <td>${t.revoked?"":`<button class="ghost" onclick="revoke('${t.id}')">revoke</button>`}</td></tr>`).join("");
+}
+async function refreshLogs() {
+  const d = await (await api("/admin/logs?limit=60")).json();
+  document.getElementById("logs").innerHTML = d.logs.map(g => `
+    <tr><td class="mono">${new Date(g.ts_ms).toLocaleTimeString()}</td><td>${g.token_label||""}</td>
+    <td>${g.provider||""}</td><td class="mono">${(g.model||"").slice(0,26)}</td>
+    <td>${g.status||""}</td><td>${g.prompt_tokens??"-"}</td><td>${g.completion_tokens??"-"}</td><td>${g.latency_ms||""}</td></tr>`).join("");
+}
+async function mint() {
+  const body = { label: val("t_label")||"machine", scope: (val("t_scope")||"*").split(",").map(s=>s.trim()), ttl_seconds: parseInt(val("t_ttl"))||null };
+  const d = await (await api("/admin/tokens", { method:"POST", body: JSON.stringify(body) })).json();
+  const el = document.getElementById("minted"); el.classList.remove("hide");
+  el.innerHTML = `<b>Token (shown once):</b><br/><span class="mono">${d.token}</span>`;
+  refreshTokens(); boot();
+}
+async function revoke(id) { await api("/admin/tokens/"+id, { method:"DELETE" }); refreshTokens(); }
+function val(id){ return document.getElementById(id).value.trim(); }
+
+if (A()) boot();
+setInterval(() => { if (A() && !document.getElementById("app").classList.contains("hide")) { refreshLogs(); } }, 4000);
+</script>
+</body>
+</html>

proxyagent-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+proxyagent/__init__.py,sha256=grcI_bPMZCUvI2GB5tPrPoG29sc0Tgbi_69kNI5Bq3E,2289
+proxyagent/cli.py,sha256=fKhTiqkRynVsnTcQvLFMLX37_1wvQl-YysH9eiAdDVQ,6217
+proxyagent/config.py,sha256=RJNm6zATUAou8OblJeMnNOoKTWJWjexDIfqB_ju478I,2841
+proxyagent/harness.py,sha256=C5pE0mbSi_WBGXznYh0rDEwcODkFYZJ-L_EmvKyocks,2604
+proxyagent/providers.py,sha256=bX_grMoyUVbaImhCPPeTSopi4xmo4NCHjwkQ2qKK9Vo,4275
+proxyagent/security.py,sha256=mzQwhEe6ApCk9cRCKS3DGihb3sb-PgDvkqU_BQnNhq0,2022
+proxyagent/server.py,sha256=ZWlnddqamjdo6hacviy-mXstr_ZGgDlTXexXRFCUMJQ,8234
+proxyagent/store.py,sha256=bvTE59cqx_wyUKL7Ik4KyGyUtamCG_yvgx0N74JTsrM,5367
+proxyagent/tools.py,sha256=kW5wui_iQ9el0inwIotkk2CxNbtJm2EJ1IGyx388xEg,5598
+proxyagent/ui/index.html,sha256=WnQWgXwItDkZEH5na_xPvoDnlLIgBY5WaUxwm6Ilo7M,8082
+proxyagent-0.1.0.dist-info/METADATA,sha256=liqVAjM_phze91PBXaqzeWqZD8rSx7Zcdbqta8DJpRY,5589
+proxyagent-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+proxyagent-0.1.0.dist-info/entry_points.txt,sha256=kD5eHfhjVQ5Sl221LZBsZW2fxlxW4h_dvdQnjOxBGHk,50
+proxyagent-0.1.0.dist-info/RECORD,,

proxyagent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

proxyagent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+proxyagent = proxyagent.cli:app