> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nanoclaw.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Credential gateways
> How NanoClaw keeps real credentials out of agent containers with a credential gateway — OneCLI by default, Iron Proxy as an alternative — and what changes for hand-merged forks in 2.4.0.
Your assistant never receives real credentials. NanoClaw stores them in a **credential gateway** on the host, and the gateway adds them to each outbound request at the network boundary. An agent container only ever holds placeholders for the credentials the gateway manages, so a prompt injection or a misbehaving tool cannot read those keys from the container. Files you mount into the sandbox yourself are a separate matter; see [Hardening](/operate/hardening).
Since NanoClaw 2.4.0 the gateway is an installable choice rather than a built-in. This page covers which gateways exist, how setup picks one, and what to do when you update a fork by hand. For how OneCLI itself stores secrets, stubs credentials, and asks for approval, see [Credentials](/operate/credentials).
## Which gateway you get
| Gateway | How you get it | What it is |
| -------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OneCLI** (default) | Standard setup, or Advanced setup with the default kept | The OneCLI Agent Vault and its HTTPS proxy. Every new install uses it unless you choose otherwise. |
| **Iron Proxy** | Advanced setup, or `/add-iron-proxy` | One central Iron Proxy plus the Iron Control web console (Secrets, Credentials, OAuth Apps, Principals) on Docker. Each request passes the front identity and allowlist, then NanoClaw's approval step, then stored credentials, before it reaches the upstream service. Requests to the agent provider's own model domains and configured reads are approved automatically; the rest go to a human. |
**Standard setup** installs OneCLI without asking. **Advanced setup** shows a gateway picker built from the installed gateway skills, with OneCLI listed first as the default (`setup/auto.ts:183`). Setup then installs the chosen gateway and prints a one-line reminder that credentials are only added at the network boundary (`setup/auto.ts:328`).
You can also preselect a gateway before running setup:
```bash theme={null}
NANOCLAW_GATEWAY_PROVIDER=iron-proxy pnpm run setup:auto
```
The accepted kinds are `onecli` and `iron-proxy`. The host reads `NANOCLAW_GATEWAY_PROVIDER` from the process environment first, then from `.env`. A kind that no installed gateway registers is an error at startup, not a fallback to open network access.
Setting the variable alone does not install anything. Setup installs the gateway skill and then records the selection in `.env`; if you set it by hand, run the matching `/add-onecli` or `/add-iron-proxy` skill too.
## Existing installs keep their gateway
Updating does not change your gateway. Setup and `/update-nanoclaw` first look at the recorded `NANOCLAW_GATEWAY_PROVIDER`, then at which gateway is already installed, and only fall back to the default for a fresh install. An install that predates 2.4.0 and used the built-in OneCLI integration is detected and gets `/add-onecli` applied before cutover.
To reinstall or repair the gateway you already use, run its skill from the NanoClaw checkout:
* `/add-onecli` installs or refreshes OneCLI as the gateway, including its approval bridge and the agent guidance it adds to every container.
* `/add-iron-proxy` installs or refreshes Iron Proxy and Iron Control, and can set up Codex to run through it.
Do not switch gateways to get through an update. Changing gateways means re-registering your provider credentials in the new one.
## Updating a hand-merged fork to 2.4.0
**Breaking in 2.4.0.** The host refuses to start without a registered gateway. If you merge upstream into a fork by hand, install your gateway before you restart. The supported `/update-nanoclaw` path does this for you.
1. Record the pre-merge revision and back up `.env` and `data/` before you touch the live checkout.
2. Stop this copy's host and its agent containers, then merge.
3. Run `/add-onecli` for an existing OneCLI install, or the skill for the gateway you had selected. Keep its existing connection settings and credentials.
4. Confirm `.env` records the matching `NANOCLAW_GATEWAY_PROVIDER`.
5. Build, restart, and check the host log for successful gateway initialization. A startup error such as `No gateway provider is registered in this build` means the gateway payload is missing. A hand merge also trips the startup upgrade tripwire, which runs before gateway selection; [Upgrading](/operate/upgrading) explains how to clear it.
6. Send a message through an existing agent and confirm a credentialed request and an approval-gated action still work.
Forks with their own gateway wiring must implement the current contract. The upstream [gateway seam](https://github.com/nanocoai/nanoclaw/blob/main/docs/gateway-seam.md#migrating-an-existing-installation) document has the full detect, verify, and rollback procedure, and [Updating to NanoClaw 2.4](https://github.com/nanocoai/nanoclaw/blob/main/docs/release-2.4-update.md) covers the other 2.4.0 changes. See also [Upgrading](/operate/upgrading).
## For skill authors: how a gateway skill is built
A gateway is a skill directory `.claude/skills//` that contains a `gateway.json` manifest:
```json theme={null}
{ "kind": "onecli", "label": "OneCLI", "description": "Use the OneCLI agent vault and gateway.", "default": true }
```
`setup/gateways/catalog.ts` discovers gateways by that file and requires exactly one `default`. Unlike channel and provider skills, a gateway skill keeps its implementation on `main` under the skill's own `payload/` directory: an install with no gateway cannot start, so the payload has to be in the checkout setup runs from.
When the skill is applied, the payload lands in ordinary paths:
* `src/gateway-providers/.ts` — the host-side provider implementation
* `container/skills/-gateway/` — the agent-facing skill mounted into containers
* one appended line in `src/gateway-providers/installed.ts` — the registration import
Beyond those, a skill can add files of its own (OneCLI also copies its upgrade runbook into `docs/`) and declare package dependencies that the skill engine installs with `pnpm add`. At startup the host resolves exactly one provider from `NANOCLAW_GATEWAY_PROVIDER`, and only the selected gateway's agent skills are composed into a container's instructions, so an agent is not told about a gateway it is not behind. The whole `container/skills/` directory is still mounted read-only at `/app/skills`.
The contract itself, including session lifecycle, human approval, and the `gateway-trust` mount class, is in the upstream [gateway seam](https://github.com/nanocoai/nanoclaw/blob/main/docs/gateway-seam.md) document. For skill mechanics, see [Writing skills](/extend/writing-skills).