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)

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:

from openai import OpenAI
client = OpenAI()                  # picks up OPENAI_BASE_URL from .env
print(client.models.list().data[0].id)

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 as of v0.3.3

Honest list — these are tracked, not unknown.

Limitation	Tracked as
Proxy doesn’t auto-restart on reboot — you must run `worthless up` after every boot	WOR-174 (macOS launchd) + WOR-175 (Linux systemd), v1.1
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` doesn’t purge the keychain entry or `~/.worthless/`	WOR-435, v1.2
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.