Keep your castle secure and moving.

Calciforge is a self-hosted security gateway for AI agents. It sits between your agents and the rest of the world, so every agent gets its own model routes, command permissions, destination-scoped secret substitution, and audit trail without holding your raw API keys.

The longer feature tour, configuration examples, and architecture notes live on the docs site: calciforge.org.

This is usable for a solo operator, but still in active hardening. New installations should be smoke-tested against their real channel credentials, fnox store, gateway providers, and synthetic routes before being treated as daily-driver infrastructure.

git clone https://github.com/bglusman/calciforge
cd calciforge
bash scripts/install.sh
calciforge doctor

After install, the default local pieces are:

• calciforge — channel router, commands, identity, model gateway
• security-proxy on 127.0.0.1:8888 — substitution, destination checks, scanning, credential injection
• clashd on 127.0.0.1:9001 — small HTTP adapter around the clash policy engine
• secrets-client — env → fnox → Vaultwarden secret resolver
• calciforge-secrets — non-MCP secret-name discovery and {{secret:NAME}} reference helper
• paste-server — short-lived local/LAN forms for adding secrets without putting values in chat history

The installer attempts to install and initialize fnox automatically. Calciforge uses ~/.config/calciforge as its app config home by default; override it with CALCIFORGE_CONFIG_HOME. The Calciforge fnox working directory defaults to the same path (CALCIFORGE_FNOX_DIR can override it), so cd ~/.config/calciforge && fnox set/list/tui manages the same store Calciforge resolves through. On macOS, if no global fnox provider is configured, the installer adds a calciforge-local Keychain provider under ~/.config/fnox/config.toml; on Linux, it creates a local age provider backed by an Ed25519 key in ~/.config/calciforge/secrets/fnox-age-ed25519. Set CALCIFORGE_FNOX_PROVIDER_NAME, CALCIFORGE_FNOX_PROVIDER_TYPE, CALCIFORGE_FNOX_AGE_RECIPIENT, or FNOX_AGE_KEY_FILE before install to bring your own provider/key material. Treat the generated age key as secret: anyone who can read it can decrypt the local fnox store.

The installer runs calciforge doctor --no-network after installing local services when a config file is present. Run calciforge doctor again after editing config or moving services. It validates config, checks referenced secret files without printing values, flags stale active-agent/model state, detects suspicious self-routing into the local model gateway, warns if the Calciforge service itself has ambient proxy env, flags subprocess agents that explicitly set proxy env, warns about externally managed agent daemons whose outbound proxy environment cannot be proven, validates configured scanner policy files and rule syntax, and can probe configured agent endpoints. Use --no-network for a purely local check.

Channel-based secret input is intentionally being de-emphasized because chat transports can retain plaintext values. Prefer the paste UI (!secret input NAME / !secret bulk from chat, aliases of !secure input / !secure bulk, or paste-server NAME on the host) or direct fnox input for new secrets. Chat-started paste links are intended for browsers on the same local network unless you configure an authenticated reverse proxy/tunnel with CALCIFORGE_PASTE_PUBLIC_BASE_URL.

Do not put proxy variables on the Calciforge daemon itself; that can route Calciforge's own provider and control-plane traffic through its security proxy. For model traffic, configure agents to use Calciforge's OpenAI-compatible model gateway as their model API base URL; this is the ingress that makes model aliases, alloys, cascades, dispatchers, provider routing, and model observability work. Separately, configure agent tool/web traffic to use security-proxy or a Calciforge fetch/tool integration when returned content must be scanned. Do not assume CLI agents can be wrapped by setting HTTP_PROXY or HTTPS_PROXY; Codex, Claude, ACPX, npm-backed adapters, and streaming clients may use CONNECT, WebSockets, or browser-backed auth flows that the current proxy cannot inspect and may break. Use OpenAI-compatible gateway routes, explicit fetch/tool integrations, audited recipes, or tested wrappers for traffic that must pass through security-proxy.

For externally managed agent daemons that Calciforge does not launch, proxying has to be configured on that daemon or its service manager and validated against security-proxy logs:

export HTTP_PROXY=http://127.0.0.1:8888
export NO_PROXY=localhost,127.0.0.1,::1

Do not treat ambient HTTPS_PROXY as a security boundary unless it points at Calciforge's MITM listener and the agent runtime trusts the Calciforge CA. The installer enables the experimental hudsucker-backed listener and generates a persistent local CA by default; manual deployments can set SECURITY_PROXY_CA_CERT=... and SECURITY_PROXY_CA_KEY=.... Use a Calciforge-owned model gateway, fetch/tool path, audited recipe, or tested MITM proxy setup when HTTPS content needs scanning or secret substitution.

[calciforge]
version = 2

[[identities]]
id = "owner"
aliases = [{ channel = "telegram", id = "7000000001" }]
role = "owner"

[[agents]]
id = "codex"
kind = "codex-cli"
model = "gpt-5.5"
timeout_ms = 600000

[[routing]]
identity = "owner"
default_agent = "codex"
allowed_agents = ["codex"]

[proxy]
enabled = true
bind = "127.0.0.1:8080"
backend_type = "http"
backend_url = "https://api.openai.com/v1"
backend_api_key_file = "/etc/calciforge/secrets/openai-key"

[proxy.token_estimator]
strategy = "auto"

[[model_shortcuts]]
alias = "sonnet"
model = "anthropic/claude-sonnet-4.6"

chat channels ─▶ calciforge ─▶ agent
                    │            │
                    │            ▼
                    │      security-proxy ─▶ upstream APIs / web
                    │            │
                    │            ├─ secrets-client / fnox
                    │            ├─ adversary-detector
                    │            └─ clashd policy sidecar
                    │
                    └─ host-agent for narrow system operations

The key rule: agents ask for capabilities by name; Calciforge decides whether the current identity, destination, and policy context allow the operation.

cargo test
cargo test -p calciforge
cargo test -p calciforge --features tiktoken-estimator
cargo test -p secrets-client
cargo fmt --all -- --check
cargo clippy --all-targets

Install hooks once:

bash scripts/install-git-hooks.sh

• Feature tour and install notes
• Agent runtime contract
• Model gateway reference
• Codex/OpenClaw integration
• Model gateway RFC
• Security proxy docs
• Host-agent docs
• Roadmap
• Staging test matrix
• Channel secret-input deprecation note

MIT. Some bundled tools, including fnox, carry their own licenses; see the relevant crate manifests and upstream projects.