Skip to content
Worthless

Install — Pick Your Platform

Installing worthless

| Platform | Guide | Time to working proxy | |---|---|---| | macOS (Apple Silicon or Intel) | macOS guide | ~2 min on a fast network | | Linux (Ubuntu / Debian / Alpine) | Linux guide | ~1-2 min on a fast network | | Windows + WSL2 † | WSL2 guide | ~2-3 min on a fast network | | Docker (your app runs in a container) | Docker guide | ~5 min (one-time per project) |

† WSL2 is not exercised in CI. The underlying install is identical to Linux (which is CI-tested), but the WSL-specific layer — localhost forwarding, file-backed keystore, /mnt/c detection — is verified by hand, not automated. macOS, Linux, and Docker installs all run in CI.

Note: Worthless is always installed natively on your host, even if your app runs in Docker. The Docker image is for self-hosting a worthless server for a team — not for running the CLI. See Docker guide for the full explanation.

Behind a corporate proxy or with cold uv caches, add 1-2 min for the PyPI fetch.

Common to all platforms

What worthless lock does to your .env

| Before | After | |---|---| | OPENAI_API_KEY=<your-real-key-here> | OPENAI_API_KEY=<decoy-prefix>... (useless on its own) | | (no OPENAI_BASE_URL) | OPENAI_BASE_URL=http://127.0.0.1:8787/<alias>/v1 |

<alias> is a per-key identifier worthless prints during lock (e.g. openai-bab71e6a). The proxy infers the upstream provider from the alias itself, so the URL is provider-neutral.

Your app code stays the same. The OpenAI/Anthropic SDK reads OPENAI_BASE_URL and routes through the proxy automatically. The proxy reconstructs the real key only when the request passes the spend-cap gate.

Verify it works

After locking on any platform, run your app's normal SDK path:

verify.py
from openai import OpenAI
client = OpenAI()                  # picks up OPENAI_BASE_URL from .env
print(client.models.list().data[0].id)
Terminal window
python verify.py
# → prints e.g. "gpt-4o-mini"

If you see a model id, the proxy reconstructed your key, hit the upstream provider, and returned the response — without your real key ever leaving the proxy process.

Never put your real API key on a shell command line. That's the exact exfiltration worthless protects against. Use the SDK pattern above; it reads from .env at the right boundary.

Known limitations

Honest list — these are tracked, not unknown.

| Limitation | Tracked as | |---|---| | Proxy doesn't auto-restart on reboot unless you run worthless service install | Fixed by worthless service install (macOS launchd / Linux systemd) | | Docker containers can't reach 127.0.0.1:8787 from inside — edit .env to use host.docker.internal:8787 | v1.2 work | | worthless up & may exit prematurely instead of staying attached | worthless-n8tj, v0.3.4 | | Stale orphan proxy can confuse worthless up PID detection | worthless-6gkb, v0.3.4 | | uv tool uninstall worthless only removes the binary — run worthless uninstall first to restore your keys, then purge ~/.worthless/ + the keychain | see Uninstall | | No worthless CLI is exposed by docker run ghcr.io/.../worthless — you still install natively | by design; see Docker guide |

If you hit something that isn't on this list, file a GitHub issue.

Installing worthless via an AI coding agent? See agent-schema — each platform guide's ## For AI agents section carries a fenced YAML the agent can extract without parsing prose.