clearance

A local HTTP/HTTPS forward proxy that gates network egress against a hostname allowlist. Built for deny-by-default sandboxes — coding agents, CI workers, isolated build steps — where you want one choke point the sandbox can permit, with every other route to the network closed.

The proxy ships with zero compiled-in opinions about which hosts to allow. Bring your own list — either inline via env or by pointing at one or more plain-text files. Teams typically check those files into their repo so everyone shares the same baseline.

Install

npm install -g @clipboard-health/clearance
Copy

This installs two binaries: clearance (the proxy) and clearance-ensure (idempotent daemon launcher).

Raw proxy usage

CLEARANCE_ALLOW_HOSTS=api.example.com clearance
Copy

Then point tools at http://127.0.0.1:19999 with HTTP_PROXY and HTTPS_PROXY.

By default the proxy listens on 127.0.0.1:19999, allows destination port 443, and blocks private, loopback, link-local, multicast, documentation, and other non-public IP ranges after DNS resolution.

If neither CLEARANCE_ALLOW_HOSTS nor CLEARANCE_ALLOW_HOSTS_FILES is set, the proxy refuses to start.

Allow-host files

A file is a plain-text list of hosts, one per line. Blank lines are ignored, # introduces a comment to end-of-line, and trailing dots / wildcard prefixes (*.example.com) are normalized.

# AI agents
api.openai.com
api.anthropic.com

# Source code
github.com
api.github.com
*.githubusercontent.com
Copy

Point at one or more files via CLEARANCE_ALLOW_HOSTS_FILES using your platform's PATH delimiter — : on macOS/Linux, ; on Windows. The values from CLEARANCE_ALLOW_HOSTS, all referenced files, and any duplicates are concatenated and deduped.

CLEARANCE_ALLOW_HOSTS_FILES="$REPO/clearance-allow-hosts:$HOME/.config/clearance/personal-hosts" \
  clearance
Copy

This is how teams share a baseline: check a team-allow-hosts file into your repo, and let individuals layer a personal file on top via the same env var.

Configuration reference

Managed proxy: clearance-ensure

clearance-ensure checks 127.0.0.1:19999; if no proxy is listening it spawns one detached using the same env vars and waits for it to bind. Logs live at ${XDG_CACHE_HOME:-$HOME/.cache}/clearance/clearance.log, pid at …/clearance.pid.

CLEARANCE_ALLOW_HOSTS_FILES="$REPO/clearance-allow-hosts" clearance-ensure
Copy

Lifecycle subcommands

clearance-ensure accepts an optional subcommand. With none, it defaults to start (the idempotent launch above). All subcommands discover the running proxy through the pidfile.

To pick up edited allow-host files, restart in one step:

CLEARANCE_ALLOW_HOSTS_FILES="$REPO/clearance-allow-hosts" clearance-ensure restart
Copy

Safehouse integration (macOS)

Safehouse uses macOS sandbox profiles, so this section is for macOS hosts only. Safehouse allows network access by default for agent compatibility. To force a wrapped agent through this proxy, run the proxy outside Safehouse, then append a Safehouse profile that denies direct remote egress while leaving localhost open for http://127.0.0.1:19999.

The package ships a safehouse-clearance wrapper plus the matching clearance.env and clearance-only.sb profile. After a global install, the wrapper lives at $(npm root -g)/@clipboard-health/clearance/safehouse/safehouse-clearance. It ensures the proxy is running, then execs safehouse with the env file and sandbox profile alongside it. It does not parse or rewrite your arguments — anything you pass is forwarded verbatim, so put any safehouse flags before the agent command:

SAFEHOUSE_CLEARANCE="$(npm root -g)/@clipboard-health/clearance/safehouse/safehouse-clearance"

"$SAFEHOUSE_CLEARANCE" \
  --enable=cloud-credentials --env-pass=AWS_PROFILE,AWS_REGION \
  -- codex --dangerously-bypass-approvals-and-sandbox
Copy

For day-to-day agent use, configure your allow-host files and add shell aliases:

SAFEHOUSE="$(npm root -g)/@clipboard-health/clearance/safehouse"
export CLEARANCE_ALLOW_HOSTS_FILES="$HOME/code/<your-repo>/clearance-allow-hosts:$HOME/.config/clearance/personal-allow-hosts"

alias codex-proxy="$SAFEHOUSE/safehouse-clearance codex --dangerously-bypass-approvals-and-sandbox"
alias claude-proxy="$SAFEHOUSE/safehouse-claude-proxy"
Copy

safehouse-claude-proxy runs Claude through Safehouse with --permission-mode auto. When launched from a cmux terminal, it preserves cmux's Claude shim by forwarding the cmux session environment and granting read-only access to the cmux app/socket state and generated Codex hooks. The integration also grants cmux's existing Sentry cache write access so diagnostics cannot corrupt hook JSON output. It points the shim at the real Claude binary so the shim does not recurse through itself.

The cmux environment pass-through is an explicit reviewed allowlist. If a cmux update adds new CMUX_* variables to its Claude wrapper contract, safehouse-claude-proxy prints a warning naming the unreviewed variables instead of automatically passing every CMUX_* value through the sandbox.

For AWS SSO work, log in on the host first, then layer the safehouse cloud credentials flag through the wrapper:

aws sso login --profile <profile>
AWS_PROFILE=<profile> "$SAFEHOUSE/safehouse-clearance" \
  --enable=cloud-credentials --env-pass=AWS_PROFILE,AWS_REGION,AWS_SDK_LOAD_CONFIG,AWS_CONFIG_FILE,AWS_SHARED_CREDENTIALS_FILE,AWS_CA_BUNDLE \
  -- codex --dangerously-bypass-approvals-and-sandbox
Copy

Make sure your allow-host file includes the AWS endpoints you need (typically *.amazonaws.com, *.api.aws, *.awsapps.com, *.ecr.aws).

Manual setup

If you'd rather not depend on the bundled assets, you can build the same setup by hand.

mkdir -p ~/.config/agent-safehouse
Copy

cat > ~/.config/agent-safehouse/clearance-only.sb <<'SB'
;; Force remote network egress through the local clearance while keeping
;; localhost available for local-only agent workflows.
(deny network-outbound
  (remote ip "*:*")
  (remote tcp "*:*")
  (remote udp "*:*"))

(allow network-outbound
  (remote ip "localhost:*")
  (remote tcp "localhost:*")
  (remote udp "localhost:*"))
SB
Copy

cat > ~/.config/agent-safehouse/clearance.env <<'ENV'
HTTP_PROXY="http://127.0.0.1:19999"
HTTPS_PROXY="http://127.0.0.1:19999"
ALL_PROXY="http://127.0.0.1:19999"
NO_PROXY="localhost,127.0.0.1,::1"

http_proxy="${HTTP_PROXY}"
https_proxy="${HTTPS_PROXY}"
all_proxy="${ALL_PROXY}"
no_proxy="${NO_PROXY}"
ENV
Copy

Then run the wrapped command with Safehouse:

safehouse \
  --env="$HOME/.config/agent-safehouse/clearance.env" \
  --append-profile="$HOME/.config/agent-safehouse/clearance-only.sb" \
  -- <agent-command>
Copy

Do not pass API-key environment variables just for proxying. The env file only supplies proxy settings; agents should continue to use their normal auth/config stores.

Quick checks:

# Should use the proxy and usually return 401 without auth.
safehouse --env="$HOME/.config/agent-safehouse/clearance.env" \
  --append-profile="$HOME/.config/agent-safehouse/clearance-only.sb" \
  -- curl -I https://api.openai.com/v1/models

# Should fail because this bypasses the proxy and tries direct egress.
safehouse --env="$HOME/.config/agent-safehouse/clearance.env" \
  --append-profile="$HOME/.config/agent-safehouse/clearance-only.sb" \
  -- curl --noproxy '*' -I https://api.openai.com/v1/models

# Should be denied by the proxy unless example.com is in your allow-host list.
safehouse --env="$HOME/.config/agent-safehouse/clearance.env" \
  --append-profile="$HOME/.config/agent-safehouse/clearance-only.sb" \
  -- curl -I https://example.com
Copy

Hacking on clearance

For developers working on the package itself, the source lives in ClipboardHealth/core-utils. After npm install in the repo, the bin scripts dispatch through a runCli helper that detects no compiled JS and re-execs node with --conditions @clipboard-health/source, so the proxy runs straight from TypeScript source — no build step:

cd ~/dev/c/core-utils
CLEARANCE_ALLOW_HOSTS=api.example.com node ./packages/clearance/bin/run.js
Copy

Requires Node ≥ 24.3 (native .ts type stripping enabled by default).