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 with Anthropic, Azure Foundry, AWS Bedrock, or an OpenAI-compatible service. 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

Get the installer for your platform from the downloads page.

Windows (PowerShell)

# from the extracted release folder
powershell -ExecutionPolicy Bypass -File .\install.ps1

macOS

Download the .pkg. Apple signing is temporarily unavailable, so macOS may require you to approve it under System Settings > Privacy & Security before installation. From Terminal:

sudo installer -pkg ./sifter-vX.Y.Z-macos-arm64.pkg -target /

Linux

# from the extracted release folder
sh ./install.sh

Container

Download the signed image tarball from Downloads, then:

docker load -i sifter-vX.Y.Z-container-image.tar
docker run -p 8787:8787 \
  -e SIFTER_LICENSE_FILE=/var/lib/sifter/license.json \
  -v /path/to/license.json:/var/lib/sifter/license.json \
  sifter:vX.Y.Z

3 · Activate your license

Activate the downloaded .lic certificate once. Sifter validates it locally and writes activation state beside its configuration in your platform's application-data directory; no phone-home is required to serve traffic.

# Windows
sifter license activate --token "$env:USERPROFILE\Downloads\sifter.lic"
sifter license status

# macOS / Linux
sifter license activate --token "$HOME/Downloads/sifter.lic"
sifter license status

For a container, activate once with SIFTER_LICENSE_FILE set to a host-side license.json, then mount that generated JSON at the same container path shown above. For secret-managed deployments, inject the certificate contents through SIFTER_LICENSE_TOKEN instead.

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 · Configure and start Sifter

Run the guided setup. It asks which provider you use, validates the endpoint, credential, and model before writing anything, and stores the configuration in your platform's local application-data directory.

sifter setup

Choose Anthropic, Azure Foundry, AWS Bedrock, or an OpenAI-compatible provider. Provider credentials are entered with hidden input. Sifter's benchmark-certified optimization defaults are built in, so the wizard does not ask you to tune them.

Install and start Sifter as a background service:

# Windows: run in an elevated PowerShell window
sifter service install

# macOS and Linux: installs a per-user service
sifter service install

To run it in the foreground instead, use sifter serve. The default local address is http://127.0.0.1:8787.

5 · Connect Claude Code

Sifter can configure Claude Code without asking you to manage gateway environment variables:

sifter integrate claude-code
sifter claude

sifter integrate claude-code safely merges the local gateway settings into Claude Code's settings file. sifter claude is the recommended launcher: it applies the settings only to that process, prepares or incrementally refreshes the current repository index, and waits until the index is ready before opening Claude Code. Your upstream provider key stays with Sifter and is never copied into the Claude Code environment.

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.

6 · Verify it's working

sifter doctor --validate-provider

Doctor reports every effective setting and where it came from, checks storage and licensing, and repeats the provider probe. It redacts secrets automatically.

# service health 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).
• Open http://127.0.0.1:8787/dashboard for setup status, request activity, cache behavior, and provider-cost telemetry.
• After a few real sessions, compare: your provider's usage console is the ground truth. Long, context-heavy sessions are where the gap opens.

7 · Repository indexing

sifter claude handles this automatically for the current repository. Use sifter claude --reindex to force a complete rebuild, or sifter claude --no-index to explicitly skip preparation. The manual commands remain available for other clients:

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

8 · Troubleshooting

• Provider authentication or endpoint error: rerun sifter setup. It validates the credential, endpoint, and model before replacing the existing configuration.
• Azure public access disabled: connect to the required VPN/private endpoint or change the Azure network policy, then rerun setup. The validator distinguishes this from a bad credential.
• Claude Code still calls the provider directly: rerun sifter integrate claude-code, or launch it with sifter claude.
• "License notice" in logs, features off: run sifter license status. SIFTER_LICENSE_FILE must point to generated license.json activation state, not the downloaded .lic certificate. Traffic still flows.
• Port in use: pick another with sifter serve --port and update ANTHROPIC_BASE_URL to match.
• Anything else: sifter doctor --validate-provider produces a redacted diagnostic (secrets removed, payloads omitted) you can attach to a support request.

9 · Team hosting on Azure

One shared Sifter serves a whole team (licensing stays per developer). The shape that fits Azure Container Apps: exactly one replica — Sifter keeps per-session routing and cache state locally, so it must not scale horizontally — with 2 vCPU / 4 GiB comfortably serving a team of 25–50 developers.

Push the image from the downloads tarball into your registry:

docker load -i sifter-v0.1.0-container-image.tar
az acr login --name <yourRegistry>
docker tag sifter:v0.1.0 <yourregistry>.azurecr.io/sifter:v0.1.0
docker push <yourregistry>.azurecr.io/sifter:v0.1.0

This example routes upstream through Claude on Azure (Microsoft Foundry) using your Azure deployment: AZURE_CLAUDE_ENDPOINT and AZURE_CLAUDE_DEPLOYMENT come from your Azure AI deployment blade, AZURE_CLAUDE_KEY is its key. One Azure-specific note: Foundry addresses models by deployment name, so both routing lanes are pinned to your deployments (Opus-class strong, Sonnet-class cheap) rather than following the agent's requested model id. Secrets carry the provider key, team bearer token, and raw license certificate; the certificate is injected through SIFTER_LICENSE_TOKEN.

az containerapp env create -g sifter-rg -n sifter-env --location eastus2

az containerapp create -g sifter-rg -n sifter --environment sifter-env `
  --image <yourregistry>.azurecr.io/sifter:v0.1.0 `
  --registry-server <yourregistry>.azurecr.io `
  --target-port 8787 --ingress external `
  --min-replicas 1 --max-replicas 1 `
  --cpu 2 --memory 4Gi `
  --secrets azure-claude-key=<AZURE_CLAUDE_KEY> team-token=<shared-bearer-token> sifter-lic="$(Get-Content sifter.lic -Raw)" `
  --env-vars SIFTER_UPSTREAM_PROVIDER=azure_foundry `
             SIFTER_AZURE_FOUNDRY_BASE_URL=<AZURE_CLAUDE_ENDPOINT> `
             AZURE_CLAUDE_KEY=secretref:azure-claude-key `
             SIFTER_AZURE_FOUNDRY_API_KEY_ENV=AZURE_CLAUDE_KEY `
             SIFTER_AZURE_FOUNDRY_API_KEY_HEADER=authorization_bearer `
             SIFTER_AZURE_FOUNDRY_MODEL=<AZURE_CLAUDE_DEPLOYMENT> `
             SIFTER_MODEL_ROUTING_STRONG_MODEL=<AZURE_CLAUDE_DEPLOYMENT> `
             SIFTER_MODEL_ROUTING_CHEAP_MODEL=<your-sonnet-deployment-name> `
             SIFTER_LOCAL_AUTH_TOKEN=secretref:team-token `
             SIFTER_AUTH_MODE=bearer_required `
             SIFTER_LICENSE_TOKEN=secretref:sifter-lic `
             SIFTER_STORAGE_ROOT=/var/lib/sifter

Each developer then points their agent at the app's HTTPS ingress URL with the team token, and remaps Claude Code's model aliases to your deployment names — by default Claude Code requests public Anthropic ids like claude-opus-4-8 that Azure cannot serve, and its background calls use the haiku alias:

$env:ANTHROPIC_BASE_URL = "https://sifter.<env-id>.eastus2.azurecontainerapps.io"
$env:ANTHROPIC_AUTH_TOKEN = "<shared-bearer-token>"
$env:ANTHROPIC_MODEL = "<AZURE_CLAUDE_DEPLOYMENT>"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "<AZURE_CLAUDE_DEPLOYMENT>"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "<your-sonnet-deployment-name>"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "<your-sonnet-deployment-name>"

Verify with /health on the ingress URL. Two operational notes: with default ephemeral storage, warm state (cache keepalive plans, session stickiness) resets on restart — harmless for a trial, and for durable hosting mount an Azure Files share and point SIFTER_STORAGE_ROOT at it. And keep it one replica; if you outgrow an instance, run one Sifter per team rather than scaling this one out.

10 · 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.