# Deploying Any Agent on ORB Cloud

This guide is for any agent framework. Follow the steps in order.

## Step 1: Set `[llm] base_url` in orb.toml

Every agent on ORB needs this. It tells ORB where your LLM provider lives.

```toml
[llm]
base_url = "https://api.anthropic.com"
```

Common values:

| Provider | base_url |
|----------|----------|
| Anthropic (Claude) | `https://api.anthropic.com` |
| OpenAI (GPT) | `https://api.openai.com` |
| Google (Gemini) | `https://generativelanguage.googleapis.com` |
| z.ai Coding Plan | `https://api.z.ai/api/anthropic` |
| OpenRouter | `https://openrouter.ai/api/v1` |
| Groq | `https://api.groq.com/openai` |
| Together AI | `https://api.together.xyz` |
| DeepSeek | `https://api.deepseek.com` |
| Self-hosted | `https://your-server.com` |

## Step 2: Check if your framework reads ORB's env vars

ORB automatically injects these environment variables into your agent process:

| Env var | Value | Frameworks that read it |
|---------|-------|------------------------|
| `ANTHROPIC_BASE_URL` | `http://127.0.0.1:8080` | Claude Code, Anthropic Python/JS SDK, Mastra |
| `OPENAI_BASE_URL` | `http://127.0.0.1:8080` | OpenAI Python/JS SDK, CrewAI, AutoGPT |
| `OPENAI_API_BASE` | `http://127.0.0.1:8080` | SWE-agent, older OpenAI SDK versions |
| `LLM_BASE_URL` | `http://127.0.0.1:8080` | OpenHands, LiteLLM-based frameworks |
| `GOOGLE_API_BASE_URL` | `http://127.0.0.1:8080` | Google AI SDK |
| `ORB_PROXY_URL` | `http://127.0.0.1:8080` | Custom agents (generic) |

**If your framework reads any of these, you're done. No extra config needed.** The framework will send LLM calls through ORB's proxy automatically.

**How to check:** Look at your framework's documentation for "base_url", "api_base", or "custom endpoint" configuration. If it reads one of the env vars above, it will work automatically on ORB.

## Step 3: If your framework does NOT read any of these env vars

Some frameworks use config files instead of env vars. You need to manually point the framework at ORB's proxy.

**Set the base URL to `http://127.0.0.1:8080` in your framework's config.**

| Framework | Where to set it | Example |
|-----------|----------------|---------|
| OpenClaw | `~/.openclaw/openclaw.json` | `"baseUrl": "http://127.0.0.1:8080"` |
| OpenCode | `opencode.json` | `"baseURL": "http://127.0.0.1:8080"` |
| Hermes | `~/.hermes/config.yaml` | `base_url: "http://127.0.0.1:8080"` |
| browser-use | In code | `ChatOpenAI(base_url="http://127.0.0.1:8080")` |
| Any other | Check framework docs | Set base URL / API endpoint to `http://127.0.0.1:8080` |

You can set this in your `[build]` steps in orb.toml. For example:

```toml
[build]
steps = [
  "pip install your-framework",
  "mkdir -p ~/.your-framework",
  "echo '{\"base_url\": \"http://127.0.0.1:8080\"}' > ~/.your-framework/config.json",
]
```

Or set it at runtime in your agent's entry script before making LLM calls.

## Step 4: Verify

After deploying, check the runtime logs. You should see:

```
INFO orb_runtime::proxy: Forwarding request agent_id=XXXXX path=/v1/messages
INFO orb_runtime::proxy: Response buffered agent_id=XXXXX status=200 bytes=XXXXX
```

This means LLM calls are going through the proxy. Checkpoint optimization is active.

**If you see this instead:**

```
WARN orb_runtime::transparent_proxy: LLM domain detected (bypass)
```

Your agent is calling the LLM directly, bypassing the proxy. This means:
- Your framework is NOT reading any of ORB's env vars
- You need to set the base URL manually (Step 3)
- Until fixed: your agent works, but checkpoint during LLM calls is disabled. Active LLM connections may break on checkpoint/restore.

## How the proxy works

```
Your agent
  |
  |  Framework reads ANTHROPIC_BASE_URL (or OPENAI_BASE_URL, etc.)
  |  Sends HTTP request to http://127.0.0.1:8080
  |
  v
ORB Proxy (port 8080, plaintext HTTP)
  |
  |  Forwards request to [llm] base_url over TLS
  |  Buffers the full response
  |  Signals the scheduler (may checkpoint your agent during the wait)
  |  Delivers response to your agent on restore
  |
  v
LLM Server (api.anthropic.com, openrouter.ai, etc.)
```

The proxy sees plaintext HTTP. It knows exactly when the request starts and the response ends. This is how ORB can checkpoint your agent during LLM waits and restore it when the response arrives.

## If you're building your own framework

Read `ORB_PROXY_URL` from the environment and use it as your LLM base URL:

```python
import os
base_url = os.environ.get("ORB_PROXY_URL", "https://api.anthropic.com")
```

```javascript
const baseUrl = process.env.ORB_PROXY_URL || "https://api.anthropic.com";
```

```go
baseURL := os.Getenv("ORB_PROXY_URL")
if baseURL == "" {
    baseURL = "https://api.anthropic.com"
}
```

This makes your framework ORB-compatible with zero user config.