{"slug": "show-hn-sani-let-ai-agents-use-your-tools-without-holding-your-secrets", "title": "Show HN: Sani – let AI agents use your tools without holding your secrets", "summary": "A developer publishing as sianachi released Sani, a self-hosted broker that sits between AI coding agents such as Claude Code and Codex and the credentials those agents need, so the agent holds only a Sani agent key while tokens and OAuth state stay encrypted in Sani's database on a host the agent cannot read. Each request shows the connection, tool and exact arguments and requires a person to approve it in a browser before Sani dispatches it, and shell commands needing a secret run in a throwaway Docker container with only the named secrets. A demo mode, enabled with SANI_DEMO=1 and available in Docker from v1.0.0-rc.6, provides a credential-free `demo` connection that cannot reach the network so users can see the approval flow before connecting a real platform.", "body_md": "Sani is a small self-hosted broker that sits between AI coding agents and the credentials they need. The agent never holds a token. It asks Sani to do something, a person approves that exact request in a browser, and Sani does it with the credential it keeps on its own server. The agent gets back a screened result.\n\nYou can use it two ways, together or separately:\n\n- **MCP tool calls.** Connect an authenticated MCP server such as GitHub or\nLinear. The agent requests one of the tools you enabled and Sani makes the\ncall with the stored token or OAuth sign-in.\n- **Shell commands.** Store a secret such as`GH_TOKEN` . The agent requests a\ncommand, for example`gh pr list --repo acme/site` , and Sani runs it in a\nthrowaway Docker container with only the secrets that command named. This\ncovers CLIs and plain HTTP APIs that have no MCP server. See[Run commands in the sandbox](#run-commands-in-the-sandbox) .\n\nIt works with any client that speaks MCP over HTTP, including Claude Code and Codex.\n\nDemo mode adds a built-in connection named `demo`. It stores no credential and\ncannot reach the network or other systems, so you can see the approval flow\nbefore you connect a real platform. It is off unless you set `SANI_DEMO=1`.\nReal connections are unchanged.\n\n```\nSANI_DEMO=1 npx github:sianachi/sani\n```\n\nDocker works the same way with `-e SANI_DEMO=1`, from `v1.0.0-rc.6` on. See\n[Run Sani](#run-sani).\n\n1. Sani prints a sign-in address and, on the first run, your operator password.\n2. Open [http://127.0.0.1:8765](http://127.0.0.1:8765) and sign in. Use that host for the approval\nlink as well:`localhost` is a different site to the browser. The console\nshows demo mode and the`demo` connection, with`lookup_ticket` enabled.\n3. Create an agent token. Sani shows it once.\n4. Request a demo lookup. Sani does not run it until you approve:\n\n```\nexport SANI_AGENT_KEY='sani_...'\ncurl -sS http://127.0.0.1:8765/mcp \\\n  -H \"Authorization: Bearer $SANI_AGENT_KEY\" \\\n  -H 'Content-Type: application/json' \\\n  -H 'Accept: application/json, text/event-stream' \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"request_action\",\"arguments\":{\"connection\":\"demo\",\"tool\":\"lookup_ticket\",\"args\":{\"id\":\"1001\"}}}}'\n```\n\n1. Open the `approvalUrl` from the JSON, approve the request, then read the\nscreened result (use the`id` from the same JSON):\n\n```\ncurl -sS http://127.0.0.1:8765/mcp \\\n  -H \"Authorization: Bearer $SANI_AGENT_KEY\" \\\n  -H 'Content-Type: application/json' \\\n  -H 'Accept: application/json, text/event-stream' \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"get_request\",\"arguments\":{\"id\":\"PASTE_REQUEST_ID\"}}}'\n```\n\nFrom a clone, `SANI_AGENT_KEY='sani_...' scripts/try-demo.sh` sends that\nrequest and waits until you approve. [docs/demo](https://github.com/sianachi/sani/blob/main/docs/demo) has a walkthrough\nscript and a recording.\n\nGiving an agent a GitHub or Linear token means the token lives in its shell, its config files and its context, and every tool call it makes is one you did not see. Sani changes three things:\n\n- **The credential stays out of reach.** Tokens and OAuth state are encrypted\nin Sani's database, on a host the agent cannot read. The agent holds only a\nSani agent key, which can request actions but cannot approve them.\n- **A person approves each call.** Every request shows the connection, the\ntool and the exact arguments. Nothing is sent until you approve it, and an\napproval is spent on one dispatch.\n- **Commands run away from the agent.** A command that needs a secret runs in\na locked-down container on Sani's host, so the secret never reaches the\nagent's shell, files or context.\n- **Only the tools you enable exist.** Sani lists a platform's tools and you\nswitch on the ones you want. If the platform later changes a tool's\ndefinition, Sani switches it off until you review it again.\n\n```\n agent (Claude Code, Codex)          you (browser)           platform MCP server\n        |                                 |                          |\n        |-- request_action -------------->|                          |\n        |<- approval link, request id ----|                          |\n        |                                 |-- review and approve     |\n        |                          Sani --|------- tools/call ------>|\n        |                          Sani <-|------- result -----------|\n        |-- get_request ----------------->|                          |\n        |<- screened result --------------|                          |\n```\n\n1. You add a **connection** : a name, the platform's Streamable HTTP MCP\nendpoint, and either a bearer token or an OAuth issuer.\n2. Sani discovers the platform's tools. You enable the ones agents may request.\n3. You create an **agent key** for each client. It is shown once and stored\nonly as a hash.\n4. The agent calls `request_action` . Sani checks the arguments against the\ntool's JSON Schema, stores the request and returns an approval link.\n5. You open the link, sign in, and approve or decline.\n6. On approval Sani re-reads the tool from the platform, confirms it still matches what you enabled, and sends the call once with the stored credential.\n7. Sani screens the reply for stored credentials and keeps the text and\nstructured data. The agent fetches it with `get_request` .\n\nA shell command follows the same path: the agent calls `request_command`, you\napprove the exact command line, and Sani runs it once in the sandbox and\nreturns the exit code and screened output.\n\nSani is itself an MCP server at `<SANI_ORIGIN>/mcp`. It exposes these tools:\n\n| Tool | Purpose | \n|---|---|\n| `list_actions` | List the enabled actions and their argument schemas, and the sandbox's secret names | \n| `request_action` | Ask for one action; returns a request ID and an approval link | \n| `request_command` | Ask to run one shell command in the sandbox; present only when the sandbox is on | \n| `get_request` | Read the status, and the result once there is one, of the agent's own request | \n\nAn agent can read only the requests it made. Errors returned to the agent are fixed sentences, because platform and storage errors can carry credentials or submitted arguments.\n\n| State | Meaning | \n|---|---|\n| `pending` | Waiting for your decision | \n| `expired` | Nobody decided within 15 minutes | \n| `declined` | You declined it, or the arguments contained a stored credential | \n| `running` | Approved and being sent | \n| `succeeded` | The platform answered and the result passed screening | \n| `failed` | The call was not sent, the platform reported an error, or the result was withheld | \n| `unknown` | The call was sent and Sani cannot confirm the outcome, for example after a timeout or a restart | \n\nEvery state after `pending` is final. A retry is a new request and needs a new\napproval.\n\nPick one. Each prints a sign-in address and, on the first run, your operator password. There is nothing to configure first.\n\n**With Node.js** (24.13 or newer), nothing to clone:\n\n```\nnpx github:sianachi/sani\n```\n\n**With Docker:**\n\n```\ndocker run --init -p 127.0.0.1:8765:8765 -v sani-data:/app/data ghcr.io/sianachi/sani\n```\n\nThe image is public and built for `linux/amd64` and `linux/arm64`. Pin a\nversion with a tag such as `ghcr.io/sianachi/sani:v1.0.0-rc.6`.\n\n**From source:**\n\n```\ngit clone https://github.com/sianachi/sani.git\ncd sani\nnpm ci\nnpm start\n```\n\nThen open `http://127.0.0.1:8765`, sign in, and follow **Get started** on the\npage:\n\n1. Add a connection (the form has one-click starting points for Linear and GitHub) or save a secret for sandbox commands.\n2. Create an agent token. Sani shows the exact command that connects Claude Code, the settings for Codex, and the URL and header for any other MCP client.\n3. Ask your agent to use Sani and approve its requests. Sani tells a connected agent how to use it, so there is nothing else to install.\n\nOn the first run Sani creates the operator password and an encryption key and\nsaves them with its database in `~/.sani` (the `sani-data` volume under\nDocker). If you forget the password, it is in `~/.sani/sani.env`; under Docker\nit is in the first lines of `docker logs`.\n\nTo change the password, edit `SANI_ADMIN_PASSWORD` in that file, or in your\nenvironment if you set it there, and restart Sani. Changing it signs out every\nopen console session. Sani has no in-app password change and does not store\nthe password in its database: sign-in compares what you type with the\nconfigured value.\n\nTo let agents run commands, build the sandbox image once and restart Sani. This needs Docker, and Sani itself running outside Docker:\n\n```\nnpx github:sianachi/sani sandbox\n```\n\nThe first-run setup keeps the encryption key beside the database, which is convenient and fine for trying Sani out. Before you store credentials that matter:\n\n- Set `SANI_ADMIN_PASSWORD` and`SANI_ENCRYPTION_KEY` yourself, for example\nin the environment or an env file, and keep the key separate from the\ndatabase backup. Losing the key requires re-enrolling your connections.\n- Run Sani on a trusted host or isolated account outside the agents' shell, file, and container-management access.\n- Set `SANI_ORIGIN` to an HTTPS origin behind a reverse proxy. Configure the\nproxy to omit request bodies, Authorization headers, and OAuth callback\nquery strings from access logs.\n- Run one Sani process per database.\n\n| Setting | Purpose | \n|---|---|\n| `SANI_ADMIN_PASSWORD` | Browser sign-in password, at least 16 characters. Created on first run if neither this nor the key is set | \n| `SANI_ENCRYPTION_KEY` | 32 random bytes encoded as base64url. Created on first run likewise | \n| `SANI_ORIGIN` | Browser origin used for approval links, session cookies and the OAuth callback. HTTPS, or HTTP on loopback. Default `http://127.0.0.1:8765` | \n| `SANI_HOST` ,`SANI_PORT` | Listener address and port, default `127.0.0.1` and`8765` | \n| `SANI_DB` | SQLite path, default `~/.sani/sani.sqlite` (`/app/data/sani.sqlite` in the Docker image) | \n| `SANI_SANDBOX_IMAGE` | Docker image for sandbox commands. Unset means Sani uses the `sani-sandbox` image if you built it, and otherwise the sandbox is off | \n| `SANI_DEMO` | Set to `1` or`true` to install the built-in demo connection. Unset,`0` , or`false` leaves it off. Any other value refuses to start | \n\n1. Add a named connection to the platform's Streamable HTTP MCP endpoint.\nGive Sani a restricted bearer token or choose OAuth and enter the\nplatform's trusted issuer. For OAuth, complete the provider sign-in in\nyour browser. Sani pins discovery to that issuer. For a pre-registered\nOAuth client, enter its client ID and secret in **OAuth settings** , and\nuse the callback URL shown there when registering the app.\n2. Refresh the tool list as needed and enable the exact tools you want. Sani disables a changed tool after refresh so you can review it.\n3. Create an agent access key for each client. Sani shows it once. Put it in that client's private MCP configuration. The agent key can request actions and retrieve its own results. Browser sign-in is required to approve.\n\nSuggested first connections:\n\n- **GitHub.** Use`https://api.githubcopilot.com/mcp/x/pull_requests/readonly` and a[GitHub App registered for OAuth](https://github.com/github/github-mcp-server/blob/main/docs/host-integration.md) .\nGive the app**Pull requests: Read-only** permission and install it on\nthe test repository. Choose OAuth, enter`https://github.com/login/oauth` as the issuer, and supply the app's client ID, client secret, and`offline_access` scope. A repository-scoped bearer token is also supported.\n- **Linear.** Use the[read-only Linear MCP server](https://linear.app/docs/mcp) at`https://mcp.linear.app/mcp/readonly` . Choose OAuth and enter`https://mcp.linear.app` as the issuer. Enable an issue lookup and read a test issue.\n\nSome platforms have a CLI and no MCP server. For those, an agent can ask Sani to run a shell command with a stored secret in its environment.\n\n1. Run `npx github:sianachi/sani sandbox` (or`npm run sandbox:build` in a\nclone). It builds the`sani-sandbox` image, which holds`curl` ,`jq` ,`git` and`gh` . To add tools, edit`sandbox/Dockerfile` in a clone and rebuild.\nIf you add the`gh` CLI's token as a secret, name it`GH_TOKEN` .\n2. Restart Sani. It uses that image when it exists. To use a different image,\nset `SANI_SANDBOX_IMAGE` ; Sani never pulls an image for you. The host needs\nthe`docker` CLI and access to a Docker daemon.\n3. In the console, add **Sandbox secrets** . The name is the environment\nvariable the command sees, for example`GH_TOKEN` .\n4. The agent calls `request_command` with a command and the secret names it\nneeds. You see the exact command and the names, and approve or decline.\n5. Sani runs `sh -c <command>` in a new container and returns the exit code\nand the combined output.\n\nEach run gets a fresh container that is removed afterwards. It runs as an\nunprivileged user with all capabilities dropped, a read-only filesystem apart\nfrom a 64 MiB `/tmp`, no host mounts, 512 MiB of memory, one CPU and a 60\nsecond limit. It receives only the secrets the request named. Commands run one\nat a time.\n\nReplacing or removing a secret invalidates the requests waiting on it. A\ncommand that fails to start is `failed`; one that times out is `unknown`,\nbecause it may have acted before it was stopped. A non-zero exit code is a\n`succeeded` request with that exit code in the result.\n\nThe official Sani image does not contain Docker. To use the sandbox, run Sani directly on the host, or give its container a Docker CLI and daemon access, which is equivalent to root on that host.\n\nCreating an agent token shows a ready-to-run command for Claude Code:\n\n```\nclaude mcp add --transport http sani <SANI_ORIGIN>/mcp --header \"Authorization: Bearer sani_...\"\n```\n\nFor any other client, connect it to `<SANI_ORIGIN>/mcp` with its own Sani agent key in the\nHTTP Authorization header (`Authorization: Bearer sani_...`). Use the client's\n[Claude Code MCP configuration](https://code.claude.com/docs/en/mcp) or\n[Codex MCP configuration](https://learn.chatgpt.com/docs/extend/mcp?surface=cli).\n\nFor Codex, the token page shows the `~/.codex/config.toml` entry to paste.\n\nSani sends its usage instructions to every connected client, telling the\nagent to request actions through Sani, hand you the approval link, wait, and\nkeep credentials out of chat and tool arguments. If your client ignores\nserver instructions, copy `skills/use-sani` into its skills directory for\n[Claude Code](https://code.claude.com/docs/en/skills) or\n[Codex](https://learn.chatgpt.com/docs/build-skills).\n\nAsk the client to use an enabled action. Open the Sani approval link to review the connection, tool, and exact arguments. Approving dispatches the request once. The agent fetches the result using the original agent key.\n\n**Credentials at rest.** Bearer tokens, OAuth tokens, OAuth client secrets and\nsandbox secrets are encrypted with AES-256-GCM under `SANI_ENCRYPTION_KEY`, bound to the\nconnection's ID, revision and URL. Agent keys and OAuth state values are\nstored as SHA-256 hashes. Request arguments and results are stored as plain\nJSON in the database, so protect the database file like the data it holds.\n\n**Demo mode.** `SANI_DEMO=1` adds one built-in connection named `demo`. Its\ntools return fixed sample data from inside the process. The connection has no\ntoken, and approving a demo request does not open a network connection. Demo\nmode does not relax checks on any other connection. Turn it off before you\nrely on Sani for real credentials. The reserved name `demo` is left alone if\nyou already created a real connection with that name.\n\n**Outbound calls.** Sani talks to platforms over public HTTPS only. It refuses\nredirects and private, loopback and link-local addresses, checks the resolved\naddress at connection time, pins OAuth discovery to the issuer you entered,\nand uses PKCE. Responses are capped at 1 MiB and calls time out after 15\nseconds.\n\n**Screening.** Tool definitions, request arguments and results are checked for\nevery stored credential, as plain text, URL-encoded, base64 and base64url.\nMatching data is withheld. Results are limited to text and structured data up\nto 64 KiB. The screening guarantee covers the stored credentials and the\nencodings checked by the test suite; it is not a general secret scanner.\n\n**Sandbox commands.** The container isolates the command from the Sani host,\nits database and its key. It does not isolate the secret from the command: a\ncommand holding `GH_TOKEN` can send it to any host the container can reach,\nor print it in a form screening does not recognise. The container has normal\noutbound network access, including to private addresses reachable from the\nhost. Your review of the exact command is the control, so decline anything\nyou do not fully understand, and give each secret the narrowest scope the\nprovider allows.\n\n**Approval.** Only a signed-in operator can approve. The session cookie is\nHttpOnly and SameSite, lasts 8 hours, and is invalidated by changing the\noperator password or the encryption key. A request is bound to the tool\ndefinition and connection revision it was made against, so changing a\ncredential or a tool invalidates the requests waiting on it.\n\n**Still your job.** Treat external tool descriptions and results as untrusted\ndata. There is one operator account and no built-in sign-in throttling, so put\nSani behind a reverse proxy that rate-limits and serves HTTPS. Sani has not\nhad an independent security audit.\n\nRotate or remove a platform credential to invalidate earlier approvals for that connection. Revoke a Sani agent key to stop that client. Revoke the platform token at the provider if you need to end its use outside Sani.\n\n| Limit | Value | \n|---|---|\n| Time to approve a request | 15 minutes | \n| Pending requests per agent | 25 | \n| Agent request body | 64 KiB | \n| Screened arguments or result | 64 KiB | \n| Platform response | 1 MiB | \n| Platform call timeout | 15 seconds | \n| Sandbox command length | 4096 characters | \n| Sandbox command time | 60 seconds | \n| Sandbox output returned | 16 KiB | \n| Secrets per command | 16 | \n| Processes per database | 1 | \n\n| Path | Contents | \n|---|---|\n| `src/index.ts` | Reads the environment and starts the HTTP server | \n| `src/app.ts` | Connections, approvals and the request lifecycle | \n| `src/mcp.ts` | The MCP endpoint agents connect to | \n| `src/web.ts` | The operator pages: sign-in, connections, agent keys, approvals | \n| `src/remote.ts` | Outbound MCP and OAuth client with the network rules | \n| `src/index.ts sandbox` | The `sani-mcp sandbox` subcommand that builds the sandbox image | \n| `src/sandbox.ts` | Runs approved commands in Docker | \n| `src/setup.ts` | First-run password and key, and sandbox image detection | \n| `src/render.ts` | Result tables and the command view | \n| `sandbox/Dockerfile` | The default sandbox image | \n| `src/store.ts` | SQLite storage and encryption of stored credentials | \n| `src/guard.ts` | Encryption, fingerprints, credential screening and input checks | \n| `src/demo.ts` | The built-in demo connection. It does not touch the network | \n| `skills/use-sani` | The agent skill | \n| `scripts/try-demo.sh` | Requests the demo ticket and waits for approval | \n| `docs/demo` | Demo walkthrough script, screenshots and recording | \n| `test/` | Tests against local MCP and OAuth fixtures | \n| `.github/workflows/` | CI on every push, and the release that publishes the image | \n\nRuntime dependencies are the MCP SDK, Ajv, ipaddr.js, undici and Zod. Storage\nis Node's built-in SQLite. The sandbox uses the `docker` CLI on the host.\n\nFrom a clone Sani runs its TypeScript sources directly. The installed command\n(`sani-mcp`) runs a compiled copy in `dist/`, built by `npm run build`, because\nNode does not run TypeScript from inside `node_modules`.\n\n```\nnpm run check\nnpm test\nnpm audit --omit=dev\n```\n\nThe automated suite uses isolated HTTP MCP and OAuth fixtures. For live\nprovider acceptance, use a restricted test token and a test repository,\nthen repeat with a Linear test workspace and its browser OAuth flow. Check\nthat each action waits for approval and returns its expected result. The\nDocker sandbox test runs only when Docker and the `alpine:3` image are present.\n\nCI runs the same three commands on every push and pull request, with the Docker sandbox test included.\n\nPushing a tag `vX.Y.Z` that matches the version in `package.json` runs the\nrelease workflow. It runs the tests, publishes the multi-arch image to\n`ghcr.io/sianachi/sani` under that tag and `latest`, and creates the GitHub\nrelease. A tag with a hyphen, such as `v1.0.0-rc.6`, is marked as a\npre-release.\n\nThe same workflow publishes `sani-mcp` to npm once the repository has an\n`NPM_TOKEN` secret. Until then that step is skipped, and the way to run Sani\nwithout cloning is `npx github:sianachi/sani`.\n\nSani is a release candidate (`1.0.0-rc.6`). The interface may still change\nbefore 1.0. Start with read-only tools and restricted test credentials.\n\nWhat works today, each checked against the published code:\n\n- `npx github:sianachi/sani` and the Docker image both start with no\nconfiguration and print a first-run password.\n- MCP tool calls with bearer tokens and OAuth, and sandbox commands with stored secrets, each behind one approval.\n- Copy-ready agent setup for Claude Code, Codex and other MCP clients.\n\nKnown limits:\n\n- **Not on npm yet.**`npx sani-mcp` does not work until the package is\npublished; use the GitHub form above.\n- **No sandbox when Sani runs in Docker.** The image has no Docker client.\nRun Sani on the host to use sandbox commands.\n- **First-run setup trades safety for ease.** It stores the encryption key\nbeside the database. See[For real credentials](#for-real-credentials) .\n- **The sandbox does not contain the secret.** An approved command can send\nits secrets anywhere the container can reach. See[Security boundary](#security-boundary) .\n- **The client setup snippets are unverified against live clients.** The\nClaude Code command and the Codex settings follow each client's\ndocumentation. The MCP endpoint itself is covered by the tests.\n- **Tested on macOS and Linux.** Linux is covered by CI. Windows has not been\ntried.\n- **One operator, no sign-in throttling.** Put a rate-limiting reverse proxy\nin front of a Sani that others can reach.\n- **No independent security audit.**\n\nMIT. See [LICENSE](https://github.com/sianachi/sani/blob/main/LICENSE).", "url": "https://wpnews.pro/news/show-hn-sani-let-ai-agents-use-your-tools-without-holding-your-secrets", "canonical_source": "https://github.com/sianachi/sani", "published_at": "2026-11-20 19:38:42+00:00", "updated_at": "2026-11-20 19:44:58.210553+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "ai-safety", "developer-tools"], "entities": ["Sani", "sianachi", "Claude Code", "Codex", "GitHub", "Linear", "Docker", "MCP"], "also_reported_by": [], "takeaway": "Sani keeps agent credentials off the agent's host by brokering MCP tool calls and shell commands through human approval, running secret-bearing commands in a throwaway Docker container with only the named secrets.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/show-hn-sani-let-ai-agents-use-your-tools-without-holding-your-secrets", "markdown": "https://wpnews.pro/news/show-hn-sani-let-ai-agents-use-your-tools-without-holding-your-secrets.md", "text": "https://wpnews.pro/news/show-hn-sani-let-ai-agents-use-your-tools-without-holding-your-secrets.txt", "jsonld": "https://wpnews.pro/news/show-hn-sani-let-ai-agents-use-your-tools-without-holding-your-secrets.jsonld"}}