How It Works

Request Flow

Sandbox                    Oshu Vault                  Upstream API
  |                             |                              |
  |  CONNECT api.anthropic.com  |                              |
  |---------------------------->|                              |
  |  HTTP 200 (tunnel open)     |                              |
  |<----------------------------|                              |
  |                             |                              |
  |  POST /v1/messages          |                              |
  |  x-api-key: SEALED_abc123  |                              |
  |---------------------------->|                              |
  |                             |  POST /v1/messages           |
  |                             |  x-api-key: sk-ant-real-key  |
  |                             |----------------------------->|
  |                             |                              |
  |                             |  200 OK (response)           |
  |                             |<-----------------------------|
  |  200 OK (response)          |                              |
  |<----------------------------|                              |

Components

Sealed Tokens

When you create a session, each secret gets a unique sealed token:

Sealed tokens are 32 hex characters prefixed with SEALED_. They are:

• Opaque — no way to derive the real secret from the token
• Session-scoped — only valid for the session that created them
• Replaced on-the-fly — the proxy scans headers and bodies for the pattern

MITM Proxy

For HTTPS traffic, the proxy acts as a man-in-the-middle:

1. The sandbox sends a CONNECT request to establish a tunnel
2. The proxy presents a dynamically-generated TLS certificate signed by its CA
3. The sandbox trusts this CA via NODE_EXTRA_CA_CERTS (or system trust store)
4. The proxy decrypts traffic, replaces sealed tokens, re-encrypts, and forwards

Session Authentication

Each session has a unique ID and token, passed as Proxy-Authorization (Basic auth):

• Username: sess_<id> — identifies the session
• Password: tok_<token> — authenticates the request

This is encoded in the proxy URL: https://sess_id:tok_token@pv.oshu.dev

Egress Control & Secret Scoping

Each session has two independent controls:

• allowed_egress — network firewall: which hosts can be reached (403 for everything else)
• secret_hosts — injection scope: which hosts get sealed token replacement

const session = await client.createSession({
  secrets: { ANTHROPIC_API_KEY: "sk-ant-..." },
  secret_hosts: ["api.anthropic.com"],
  allowed_egress: ["api.anthropic.com", "*.github.com"],
});

Requests to hosts not in allowed_egress are blocked with 403. Requests to hosts not in secret_hosts pass through without replacement — sealed tokens remain intact. Both fields are optional; when omitted, all hosts are allowed / all hosts get replacement.

See Network Egress Control for full details.