> ## Documentation Index
> Fetch the complete documentation index at: https://onecli.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How the Gateway Works: Credential Injection & Signing

> OneCLI runs a transparent proxy that intercepts outgoing HTTP requests, checks them against your rules, and injects credentials from an encrypted vault.

OneCLI gives agents secure access to external services through a transparent gateway, policy engine, encrypted secret store, and web dashboard. Together, these form the **Agent Vault**: a layer that handles credential injection, access policies, and enforcement so agents never hold raw API keys.

## Architecture overview

```mermaid theme={null}
%%{init: {'theme': 'neutral', 'flowchart': {'defaultRenderer': 'elk', 'nodeSpacing': 30, 'rankSpacing': 40}}}%%
flowchart TD
    Agent["<b>Your Agent</b><br/>Makes HTTP requests<br/>authenticates with access token"]

    Gateway["<b>Rust Gateway</b><br/>port 10255 · intercepts HTTP"]

    Rules["<b>Rules Engine</b><br/>Block · Rate Limit · Manual Approval<br/>per agent · per endpoint"]

    Store["<b>Secret Store</b><br/>AES-256-GCM encryption at rest<br/>decrypted only at request time"]

    Dashboard["<b>Web Dashboard</b><br/>port 10254 · manage agents<br/>secrets · rules · audit logs"]

    Services["<b>External Services</b><br/>Google · GitHub · Slack · Jira · AWS · Stripe"]

    Agent -- "HTTP with Proxy-Authorization" --> Gateway
    Gateway --> Rules
    Rules -- "allowed" --> Store
    Rules -- "blocked / rate-limited" --> Agent
    Dashboard --> Store
    Dashboard --> Rules
    Store --> Gateway
    Gateway --> Services
```

## Connecting agents

There are two ways to route agent traffic through the gateway:

| Path                                      | How it works                                               | Best for                                                   |
| ----------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- |
| [**`onecli run`**](/guides/coding-agents) | CLI wraps a local process with proxy env vars and CA certs | Coding agents on your machine (Claude Code, Cursor, Codex) |
| [**SDK / Docker**](/guides/nanoclaw)      | SDK injects proxy config into Docker container args        | Container-based orchestrators (NanoClaw, custom)           |

Both paths use the same gateway, secrets, and policy rules.

## Rust gateway

The gateway (`apps/proxy`) is an HTTP gateway built in Rust that intercepts outbound requests, enforces rules, and injects credentials. Agents authenticate with access tokens via `Proxy-Authorization` headers.

**How it works:**

1. Your agent makes a normal HTTP request (e.g., `GET https://www.googleapis.com/calendar/v3/events`)
2. The request goes through the gateway instead of directly to the internet
3. The gateway evaluates [rules](/guides/rules). If a rule blocks or rate-limits the request, the agent receives a 403 or 429 response immediately
4. If allowed, the gateway matches the target host and path against stored secrets, decrypts the matching credentials, and injects them as HTTP headers (e.g. `Authorization: Bearer ...`) or URL query parameters (e.g. `?key=...`)
5. The request is forwarded to the service with credentials attached
6. The response passes back through to your agent unchanged

**Details:**

* Runs on port 10255
* Agents authenticate with access tokens (each agent gets its own scoped token)
* Rules are evaluated before credential injection, so blocked requests never touch your secrets
* Host and path pattern matching routes secrets to the right API endpoints
* MITM interception for HTTPS traffic
* Built in Rust for low-latency proxying

## Rules engine

The rules engine enforces policies on every request that passes through the gateway. Rules match requests by host, path, HTTP method, and agent, then apply an action:

* **Block**: Deny the request entirely (403)
* **Rate Limit**: Allow up to N requests per time window, then block (429)

Rules are evaluated before credentials are injected. A blocked request never decrypts or touches your secrets; the agent is denied at the policy layer.

See [Rules](/guides/rules) for the full guide on creating and managing rules.

## Secret store

The secret store uses AES-256-GCM encryption at rest. Secrets are decrypted only at request time, matched by host and path patterns, and injected by the gateway as HTTP headers or URL query parameters.

Credentials are never stored in plain text. The encryption key is auto-generated on first run or can be set via the `SECRET_ENCRYPTION_KEY` environment variable.

## Web dashboard

The dashboard (`apps/web`) runs on port 10254 and is where you manage everything:

* Create agents with scoped access tokens
* Add, rotate, and revoke secrets for any service
* Configure host and path patterns for credential matching
* Create rules to block or rate-limit specific operations
* See which agent accessed which service and when (audit logs)

## Auth modes

OneCLI supports two authentication modes:

| Mode                      | When to use                     | Configuration                                                     |
| ------------------------- | ------------------------------- | ----------------------------------------------------------------- |
| **Single-user** (default) | Local development, personal use | No config needed                                                  |
| **Google OAuth**          | Teams, shared instances         | Set `NEXTAUTH_SECRET`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` |

## Stack

| Component      | Technology                              |
| -------------- | --------------------------------------- |
| Gateway        | Rust (port 10255)                       |
| Web dashboard  | Next.js (port 10254)                    |
| Database       | PostgreSQL (bundled via Docker Compose) |
| Secret storage | AES-256-GCM encrypted                   |
| ORM            | Prisma                                  |

## Project structure

```
apps/
  web/            # Next.js app (dashboard + API, port 10254)
  proxy/          # Rust gateway (credential injection, port 10255)
packages/
  db/             # Prisma ORM + migrations
  ui/             # Shared UI components (shadcn/ui)
docker/
  Dockerfile      # Single-container build (gateway + web)
  docker-compose.yml
```