Getting started

From download to lower invoice in ten minutes.

This guide covers install, licensing, connecting your agent, verification, and troubleshooting. Sifter runs entirely in your environment: your provider keys and prompts never leave it.

1 · Requirements

• Windows, macOS (Apple Silicon), or Linux x64; or any container runtime for the image.
• An API-billed provider account (an Anthropic API key for Claude Code). Subscription seats (Claude Pro/Max) are not supported and not what Sifter is for.
• A license file: a free 30-day trial license from the trial page, or a purchased license delivered by email after checkout.

2 · Install

Windows (PowerShell)

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 `
  -InstallDir "$env:LOCALAPPDATA\Sifter\bin" `
  -StorageRoot "$env:LOCALAPPDATA\Sifter" `
  -AddToUserPath

macOS / Linux

INSTALL_DIR="$HOME/.local/bin" STORAGE_ROOT="$HOME/.local/share/sifter" sh ./scripts/install.sh

Container

Download the signed image tarball from Downloads (license-gated), then:

docker load -i sifter-vX.Y.Z-container-image.tar
docker run -p 8787:8787 \
  -e SIFTER_LICENSE_FILE=/run/secrets/sifter.lic \
  -v /path/to/sifter.lic:/run/secrets/sifter.lic:ro \
  sifter:vX.Y.Z

Verify what you downloaded

Every artifact ships with a Sigstore bundle and SHA-256. Verify with cosign and our published key:

cosign verify-blob --key olmsted-cosign.pub \
  --bundle sifter-vX.Y.Z-linux-x64.tar.gz.sigstore.json \
  sifter-vX.Y.Z-linux-x64.tar.gz

3 · Activate your license

Point the gateway at your license file. Verification is local and offline; no phone-home is required to serve traffic.

# Windows
$env:SIFTER_LICENSE_FILE = "$env:LOCALAPPDATA\Sifter\sifter.lic"
# macOS / Linux
export SIFTER_LICENSE_FILE="$HOME/.local/share/sifter/sifter.lic"

Fail-open, always: if the license is missing, expired, or invalid, Sifter logs a notice and serves transparent passthrough. Your agents never stop working; you just stop saving. /health reports which features are active.

4 · Connect Claude Code

Start the gateway, then point Claude Code at it. Two environment variables do the work:

# start the gateway
sifter config init
sifter serve --host 127.0.0.1 --port 8787

# in your working shell (PowerShell shown; export equivalents on macOS/Linux)
$env:ANTHROPIC_API_KEY  = "<your Anthropic API key>"   # used upstream by Sifter
$env:ANTHROPIC_BASE_URL = "http://127.0.0.1:8787"
$env:ANTHROPIC_AUTH_TOKEN = "local-sifter-token"
$env:SIFTER_LOCAL_AUTH_TOKEN = "local-sifter-token"
$env:SIFTER_AUTH_MODE = "bearer_required"
$env:SIFTER_UPSTREAM_PROVIDER = "anthropic"
$env:SIFTER_UPSTREAM_BASE_URL = "https://api.anthropic.com/v1"
$env:SIFTER_WORKSPACE_ROOT = "C:\path\to\your\repo"

claude -p "Summarize this repository in five bullets."

That's the whole integration. Claude Code behaves exactly as before; Sifter manages evidence selection, model routing, compaction, and cache economics on the wire. A one-shot setup script (setup_claude_code_gateway.ps1) that sets all of the above ships with the install.

Other clients

Codex CLI, Aider, Cline, and anything OpenAI-compatible connect the same way: point the client's base URL at Sifter (http://127.0.0.1:8787/v1 for OpenAI-style chat) with your local bearer token. The gateway forwards to your configured upstream provider.

One honest note: our published savings figures are measured with Claude Code on the Anthropic API. Other agents manage context differently, so savings will vary and have not been certified for other clients; the trial measures your actual setup. Clients that route API calls through their own cloud backend (for example Cursor's managed mode) cannot pass through a local gateway at all.

5 · Verify it's working

# health, features, and build provenance
curl -s http://127.0.0.1:8787/health | jq .
# Windows: Invoke-RestMethod http://127.0.0.1:8787/health

• features shows what your license enables (routing, compaction, prewarm, response cache).
• The dashboard (address printed at startup) shows per-session spend, model mix, cache hits, and routed share.
• After a few real sessions, compare: your provider's usage console is the ground truth. Long, context-heavy sessions are where the gap opens.

6 · Optional: index your repository

Evidence selection works best with a local index of the repos you work in:

sifter repo add C:\path\to\your\repo
sifter repo index <repo-id> --max-files 2000
sifter repo status

7 · Troubleshooting

• 401 from the gateway: the client bearer token and SIFTER_LOCAL_AUTH_TOKEN disagree, or SIFTER_AUTH_MODE is stricter than the client's headers.
• "License notice" in logs, features off: check SIFTER_LICENSE_FILE path and expiry; /health tells you exactly which check failed. Traffic still flows.
• Port in use: pick another with sifter serve --port and update ANTHROPIC_BASE_URL to match.
• Anything else: sifter doctor produces a redacted diagnostic (secrets removed, payloads omitted) you can attach to a support request.

8 · Next steps

• Buy developer licenses when the trial's numbers speak for themselves.
• Licensing & verification docs: trial flow, procurement flow, public keys, diagnostics.
• Procurement pack for your finance and security teams: methodology, certified run artifacts, signing keys.