Coding agents read your files, run your commands, and send everything they see to a model provider —
API keys, tokens, database URLs, customer emails. Ficta is a local proxy that sits between the
agent and the provider. It swaps sensitive values for placeholders before a request leaves your
machine, and swaps the real values back when the response arrives. The agent keeps working normally;
the provider never receives the real values.
Open source (MIT), runs locally per launch, no account, no telemetry.
What the provider sees
The agent runs cat .env and sends the output to the model. Without Ficta, the provider gets:
API_TOKEN=tok_9f8e7d6c5b4a39281706f5e4d3c2
DATABASE_URL=postgres://admin:[email protected]:5432/app
With Ficta, the same request reaches the provider as:
API_TOKEN=FICTA_<32 hex chars>
DATABASE_URL=FICTA_<32 hex chars>
Each placeholder is a keyed HMAC of the value, so within a session the same secret always maps to the
same placeholder and the model can still reason about it. When the model's response refers to a
placeholder, Ficta restores the real value locally before the agent sees it. If a registered secret
would still leave verbatim in a covered part of the request, Ficta blocks the request instead of
sending it.
Quick start
npm install -g @serovaai/ficta # or pnpm / bun
ficta setup # writes ~/.ficta/config.toml, optionally installs shims
ficta doctor claude # check secrets load and routing works (or: codex / pi)
claude # now runs through Ficta
No shims? Launch explicitly with ficta claude, ficta codex, or ficta pi. Overhead is about
2–3 ms per request (benchmarks).
Works with
Ficta only supports CLI agents that send all model traffic through its proxy. IDE clients such as
Cursor are not supported: their agent features bypass a custom base URL
(why).
What it protects — and what it doesn't
| Layer | Guarantee |
|---|
Registered secrets from .env, .env.local, Doppler, and secret-ish environment variables | Exact match. Fail-closed if one would leave verbatim. |
Secret shapes — API keys, JWTs, private keys, credential URLs, API_TOKEN=... (on by default) | Best effort. Catches newly pasted keys; pattern-based. |
| PII — emails, SSNs, card numbers; Presidio for broader detection (opt-in) | Best effort. Can miss values. |
Ficta does not catch secrets that are encoded or split up, unregistered values that don't look
like a known format, or anything the agent sends itself via curl, MCP tools, or other non-model
network traffic. It is secret hygiene and PII reduction, not enterprise DLP, a compliance product, or
a sandbox. Pair it with your agent's permission system and OS-level egress controls. The exact
boundary is in the threat model.
Ficta Gateway — for teams
Worried about staff pasting client data into ChatGPT? Ficta Gateway is a
self-hosted AI chat workspace on the same engine. Users see exactly what the model will receive
before they send, can protect anything the detectors missed, and admins turn those catches into
workspace policy. Provider keys stay server-side; responses are restored inside your environment.
Gateway is source-available (BUSL-1.1): free for evaluation, production use needs a commercial
license. See ficta.sh or email [email protected].
Docs
What's in this repo
See LICENSING.md for details. Gateway versions up to commit aacf45d remain
AGPL-3.0-only.
Status and contributing
Ficta uses normal semver releases. Exact-match redaction, restore, and fail-closed behavior are
covered by tests and real agent runs; run ficta doctor <agent> before relying on a setup, and test a
Gateway deployment with fake secrets and fake PII before using it on sensitive work.
Contributions welcome — start with CONTRIBUTING.md for the monorepo toolchain
and packages/ficta/CONTRIBUTING.md for the guidelines.
