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

# Architecture

> How Rigbox isolates workspaces, routes traffic, and manages AI provider access.

Rigbox separates platform operations from user code. Your workspaces run in isolated micro-VMs that have no access to platform credentials, other users' data, or control plane services.

## Workspace isolation

Each workspace is a micro-VM - not a container. This gives you:

* **Dedicated kernel** - each VM boots its own Linux kernel, fully independent from other workspaces
* **Own filesystem** - isolated ext4 disk with no shared volumes
* **Private network** - workspaces cannot communicate with each other directly
* **systemd init** - full Linux userspace with service management
* **No platform secrets** - credentials and internal tokens never enter the VM

Even if code running inside a workspace achieves root access, it is confined to that VM. It cannot reach other workspaces or platform infrastructure.

## App routing

When you expose a port from a workspace, Rigbox creates a public URL with automatic HTTPS:

```mermaid theme={null}
flowchart LR
    BROWSER[Browser] -->|HTTPS| SUB["your-app.rigbox.dev"]
    SUB --> VM["Your service\nport 3000"]
```

* Each app gets a unique subdomain of the form `<APP_NAME>.rigbox.dev`, where `<APP_NAME>` is the name you chose when creating the app
* HTTPS termination is automatic - your service only needs to listen on HTTP inside the VM
* Routes are created and removed dynamically as you add or delete apps
* [Visibility controls](/guides/visibility) determine who can access each app (public, private, or privileged)

## AI proxy

The managed AI proxy lets your workspace code call AI providers without holding API keys:

```mermaid theme={null}
flowchart LR
    CODE[Your code] -->|SDK request| PROXY["Bridge proxy\n172.16.0.1:9090"]
    PROXY -->|Authenticated| PROVIDER[Anthropic / OpenAI / Google]
    PROXY --> CREDITS[Credits deducted]
```

* Provider API keys never enter your VM - the proxy injects them at request time
* Token usage is metered and deducted from your credit balance
* Workspaces export `OPENROUTER_BASE_URL=http://172.16.0.1:9090/v1` and `OPENROUTER_API_KEY` at login so SDKs and CLI tools work out of the box; `rig proxy on` is available for shells/tools that need provider-native compatibility exports
* The proxy fronts an OpenRouter gateway: `/v1/chat/completions`, `/v1/embeddings`, and `/v1/models` for OpenAI-shape clients, plus `/v1/messages` for the native Anthropic shape used by Claude Code; `/brave` exposes Brave Search when configured

See [Managed AI Proxy](/guides/managed-proxy) for usage details and [BYOK](/guides/byok) for using your own keys.

## VM-local bridge services

Each running workspace can reach a compute-local bridge service at `http://172.16.0.1:9090`. That service hosts the managed AI proxy and the VM-scoped CLI API used by the baked-in `rig` command.

```mermaid theme={null}
flowchart LR
    VM["Workspace VM"] -->|source IP on bridge| BRIDGE["172.16.0.1:9090"]
    BRIDGE --> CLI["/rig/v1\nworkspace-scoped CLI"]
    BRIDGE --> AI["/v1 and provider paths\nAI proxy"]
```

The bridge does not trust user-supplied workspace IDs as identity. Rigbox resolves the caller from the VM source IP and the compute node that received the request. This keeps VM identity fixed even if code inside the VM edits local files.

## Regions

Workspaces run in specific regions. SSH connections to `{region}.rigbox.dev` (e.g., `eu-west-1.rigbox.dev`) connect directly to the region for lowest latency. The base hostname `rigbox.dev` routes to any region but may add latency depending on your location.

See [SSH Access](/guides/ssh-access) for connection details.

## Learn more

<CardGroup cols={2}>
  <Card title="Security & Isolation" icon="shield" href="/concepts/security">
    Credential protection, access control, and network model
  </Card>

  <Card title="Resource Limits" icon="gauge" href="/concepts/limits">
    Plan tiers, quotas, and rate limits
  </Card>
</CardGroup>