Authentication

agtOS uses API keys to authenticate with cloud AI providers. You can configure one or both providers — the system uses whichever is configured in the model slot registry.

Anthropic (Claude)

Pay-per-token billing from console.anthropic.com.

# .env.local
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here

Token prefix: sk-ant-api03-
Sent via X-Api-Key HTTP header
Direct SDK connection to api.anthropic.com

OpenAI

Pay-per-token billing from platform.openai.com.

# .env.local
OPENAI_API_KEY=sk-your-key-here

Token prefix: sk-
Used via OpenAI Node SDK v6
Supports GPT-4o and GPT-4o Mini

Cloud Provider Selection

Cloud provider selection is configured per slot in ~/.agtos/config.json via the Model Slot Registry (ADR-020). Run agtos setup to configure slots interactively, or edit the config file directly:

~/.agtos/config.json

{
  "slots": {
    "chat": { "provider": "claude", "model": "claude-sonnet-4-20250514" },
    "reasoning": { "provider": "openai", "model": "gpt-4o" }
  }
}

Each slot can use a different provider (claude, openai, ollama, openrouter). When both API keys are configured, you can mix providers across slots — e.g., Claude for chat and OpenAI for reasoning.

Claude Transport Options

By default, agtOS connects to the Anthropic API directly via the SDK. You can optionally spawn the claude CLI binary as a subprocess:

# .env.local
AGTOS_CLAUDE_TRANSPORT=sdk   # default — direct API via Anthropic SDK
# AGTOS_CLAUDE_TRANSPORT=cli # alternative — spawn claude CLI binary

When using CLI transport, the ANTHROPIC_API_KEY is passed to the subprocess as an environment variable.

CLI transport requires the claude CLI to be installed and on your PATH. Install from claude.ai/download.

Advanced Options

# Adaptive thinking (recommended for Claude 4.6)
CLAUDE_THINKING=adaptive
CLAUDE_EFFORT=medium      # low, medium, high, max

# Service tier
CLAUDE_SERVICE_TIER=auto  # auto or standard_only

# Custom API endpoint (for proxies)
ANTHROPIC_BASE_URL=http://localhost:8317

Endpoint Authentication

Optionally protect all /api/* routes with a Bearer token:

# .env.local
AGTOS_API_KEY=your-secret-api-key

When set, all API requests must include Authorization: Bearer <key>. Uses timing-safe SHA-256 comparison. When unset, endpoints are open (suitable for local development).

Authentication

Anthropic (Claude)

OpenAI

Cloud Provider Selection

Claude Transport Options

Advanced Options

Endpoint Authentication

What’s next

Providers

Environment Variables

​Anthropic (Claude)

​OpenAI

​Cloud Provider Selection

​Claude Transport Options

​Advanced Options

​Endpoint Authentication

​What’s next

Providers

Environment Variables

Anthropic (Claude)

OpenAI

Cloud Provider Selection

Claude Transport Options

Advanced Options

Endpoint Authentication

What’s next