Configuration Reference

Runra Runtime and SDK are configured via environment variables, a configuration file, or programmatic constructor options. This reference covers every available option.

Configuration Sources

Runra merges configuration from three sources in order of precedence:

1. Constructor options (highest)
2. Environment variables
3. Config file (runra.config.json or runra.config.ts) (lowest)

Config File

Location

Runra looks for a config file in these locations (checked in order):

1. runra.config.ts
2. runra.config.js
3. runra.config.json
4. ~/.runra/config.json

Format

{
  "sandbox": {
    "provider": "runra-sandbox",
    "apiKey": "rra_live_...",
    "apiUrl": "https://api.box.runra.dev",
    "defaults": {
      "image": "node:22",
      "resources": {
        "cpu": 2,
        "memoryMb": 4096,
        "diskMb": 10240
      },
      "timeoutMs": 300000,
      "idleTimeoutMs": 120000
    }
  },
  "agent": {
    "provider": "claude-code",
    "config": {
      "model": "claude-sonnet-4-20250514",
      "maxTurns": 50,
      "permissionMode": "auto-approve"
    }
  },
  "llm": {
    "provider": "anthropic",
    "config": {
      "model": "claude-sonnet-4-20250514",
      "maxTokens": 8192
    }
  },
  "observability": {
    "exporters": [
      {
        "provider": "axiom",
        "config": {
          "dataset": "runra-events",
          "batchSize": 100
        }
      },
      {
        "provider": "console",
        "config": {
          "format": "pretty"
        },
        "filter": {
          "types": ["exec.completed", "agent.error"]
        }
      }
    ]
  }
}

TypeScript config files are also supported:

// runra.config.ts
import { defineConfig } from "@runra/runtime";

export default defineConfig({
  sandbox: {
    provider: "runra-sandbox",
    apiKey: process.env.RUNRA_API_KEY,
    defaults: {
      image: "node:22",
      resources: { cpu: 2, memoryMb: 4096 },
    },
  },
  agent: {
    provider: "claude-code",
    config: { model: "claude-sonnet-4-20250514" },
  },
  observability: {
    exporters: [
      { provider: "axiom", config: { token: process.env.AXIOM_TOKEN } },
    ],
  },
});

---

Environment Variables

Core

Variable	Type	Default	Description
RUNRA_API_KEY	string	—	Runra Sandbox API key
RUNRA_API_URL	string	https://api.box.runra.dev	API base URL
RUNRA_LOG_LEVEL	string	info	Log level: debug, info, warn, error
RUNRA_CONFIG_PATH	string	—	Override config file path

Sandbox

Variable	Type	Default	Description
RUNRA_SANDBOX_PROVIDER	string	runra-sandbox	Sandbox provider
RUNRA_SANDBOX_IMAGE	string	node:22	Default sandbox image
RUNRA_SANDBOX_CPU	number	2	Default vCPUs
RUNRA_SANDBOX_MEMORY_MB	number	4096	Default memory in MB
RUNRA_SANDBOX_DISK_MB	number	10240	Default disk in MB
RUNRA_SANDBOX_TIMEOUT_MS	number	300000	Default sandbox timeout
RUNRA_SANDBOX_IDLE_TIMEOUT_MS	number	120000	Default idle timeout

Agent

Variable	Type	Default	Description
RUNRA_AGENT_PROVIDER	string	claude-code	Agent adapter
RUNRA_AGENT_MODEL	string	—	Agent model override
RUNRA_AGENT_MAX_TURNS	number	50	Max agent loops
RUNRA_AGENT_PERMISSION_MODE	string	auto-approve	Permission mode

LLM Providers

Variable	Type	Default	Description
OPENAI_API_KEY	string	—	OpenAI API key
ANTHROPIC_API_KEY	string	—	Anthropic API key
GEMINI_API_KEY	string	—	Gemini API key
OPENROUTER_API_KEY	string	—	OpenRouter API key
RUNRA_LLM_PROVIDER	string	—	LLM provider override
RUNRA_LLM_MODEL	string	—	LLM model override
RUNRA_LLM_TEMPERATURE	number	0.3	Temperature (0.0–2.0)
RUNRA_LLM_MAX_TOKENS	number	4096	Max tokens per response
RUNRA_LLM_TIMEOUT_MS	number	30000	Request timeout

Observability

Variable	Type	Default	Description
AXIOM_TOKEN	string	—	Axiom API token
AXIOM_DATASET	string	runra-events	Axiom dataset name
AXIOM_URL	string	https://cloud.axiom.co	Axiom deployment URL
OTEL_EXPORTER_OTLP_ENDPOINT	string	—	OTLP endpoint
OTEL_EXPORTER_OTLP_HEADERS	string	—	OTLP headers (key=value,...)
OTEL_SERVICE_NAME	string	runra-runtime	OTel service name
DATABASE_URL	string	—	Postgres connection string (for exporter)

CubeSandbox (Self-Hosted)

Variable	Type	Default	Description
CUBE_MASTER_URL	string	—	CubeMaster API URL
CUBE_MASTER_TOKEN	string	—	CubeMaster auth token
CUBE_TEMPLATE_NODE	string	—	Node.js template name
CUBE_TEMPLATE_PYTHON	string	—	Python template name

Docker Provider

Variable	Type	Default	Description
DOCKER_HOST	string	unix:///var/run/docker.sock	Docker socket/host
DOCKER_NETWORK_MODE	string	bridge	Network mode
DOCKER_AUTO_REMOVE	boolean	true	Auto-remove containers

---

Sandbox Options Reference

resources

Option	Values	Default	Description
cpu	2, 4, 8	2	Virtual CPUs allocated
memoryMb	2048–16384	4096	Memory in MB
diskMb	5120–51200	10240	Disk storage in MB

network

Option	Values	Default	Description
network.egress.default	"allow", "deny"	"allow"	Default outbound policy
network.egress.allow	string array	—	Allowed outbound domains
network.ingress.allowPorts	number array	—	Allowed inbound ports

Timing

Option	Min	Default	Max	Description
timeoutMs	1000	300000	86400000 (24h)	Max sandbox lifetime
idleTimeoutMs	10000	120000	3600000 (1h)	Auto-pause after idle

Images

Image	Includes
node:22	Node.js 22, npm, yarn, pnpm, git, curl, jq
node:20	Node.js 20 LTS, same tools
python:3.12	Python 3.12, pip, uv, git, curl
python:3.11	Python 3.11, same tools
ubuntu:24.04	Base Ubuntu 24.04, git, curl, jq, build-essential
ubuntu:22.04	Base Ubuntu 22.04, same tools
custom	BYO image (contact support)

---

Agent Options Reference

Option	Type	Default	Description
provider	string	"claude-code"	Agent adapter: claude-code, codex, opencode, custom
config.model	string	Provider default	LLM model for the agent
config.maxTurns	number	50	Maximum agent tool-calling loops
config.allowedTools	string[]	all	Restrict available tools
config.permissionMode	"auto-approve" | "prompt" | "plan"	"auto-approve"	Tool execution permission mode
config.workdir	string	/workspace	Agent working directory
config.systemPrompt	string	—	Override system prompt
config.apiKey	string	LLM provider key	Agent-specific API key

Available Tools by Agent

Tool	Claude Code	Codex	OpenCode
bash	✅	✅	✅
read	✅	✅	✅
write	✅	✅	✅
edit	✅	✅	✅
glob	✅	✅	✅
grep	✅	✅	✅
task	✅	—	✅
web_search	✅	—	—
web_fetch	✅	—	—

---

LLM Provider Options Reference

OpenAI

Option	Type	Default	Description
config.apiKey	string	OPENAI_API_KEY	API key
config.baseUrl	string	https://api.openai.com/v1	API endpoint
config.organization	string	—	Org ID
config.temperature	number	0.3	Sampling temperature
config.maxTokens	number	4096	Max output tokens
config.requestTimeoutMs	number	30000	Request timeout

Anthropic

Option	Type	Default	Description
config.apiKey	string	ANTHROPIC_API_KEY	API key
config.maxTokens	number	8192	Max output tokens
config.thinking.type	string	—	"enabled" for extended thinking
config.thinking.budgetTokens	number	4000	Thinking token budget

Gemini

Option	Type	Default	Description
config.apiKey	string	GEMINI_API_KEY	API key
config.temperature	number	0.3	Sampling temperature
config.maxOutputTokens	number	8192	Max output tokens
config.safetySettings	array	—	Safety filter settings

OpenRouter

Option	Type	Default	Description
config.apiKey	string	OPENROUTER_API_KEY	API key
config.baseUrl	string	https://openrouter.ai/api/v1	API endpoint
config.appName	string	—	Your app name (recommended)
config.headers	object	—	Additional HTTP headers

Ollama

Option	Type	Default	Description
config.baseUrl	string	http://localhost:11434	Ollama server URL
config.numCtx	number	32768	Context window size

vLLM

Option	Type	Default	Description
config.baseUrl	string	http://localhost:8000/v1	vLLM server URL
config.apiKey	string	—	API key (if required)

---

Observability Exporter Options Reference

Axiom

Option	Type	Default	Description
config.token	string	AXIOM_TOKEN	API or ingest token
config.dataset	string	"runra-events"	Dataset name
config.url	string	"https://cloud.axiom.co"	Axiom URL
config.batchSize	number	100	Max events per batch
config.flushIntervalMs	number	5000	Max flush interval

OpenTelemetry

Option	Type	Default	Description
config.endpoint	string	—	OTLP endpoint
config.protocol	"http/protobuf" | "grpc"	"http/protobuf"	Transport protocol
config.headers	object	—	Request headers
config.serviceName	string	"runra-runtime"	Service name
config.serviceVersion	string	—	Service version
config.spanProcessor	"batch" | "simple"	"batch"	Span processing mode
config.batchConfig.maxQueueSize	number	2048	Max queue size
config.batchConfig.maxExportBatchSize	number	512	Max batch size
config.batchConfig.scheduleDelayMs	number	5000	Batch delay

JSONL

Option	Type	Default	Description
config.filePath	string	"./runra-events.jsonl"	Output file path
config.append	boolean	true	Append to existing file
config.rotateSizeBytes	number	104857600 (100 MB)	Rotation size
config.rotateFiles	number	10	Max rotated files
config.gzip	boolean	true	Gzip rotated files

Postgres

Option	Type	Default	Description
config.connectionString	string	DATABASE_URL	Connection string
config.table	string	"runra_events"	Table name
config.schema	string	"public"	Schema name
config.batchSize	number	50	Max inserts per batch
config.flushIntervalMs	number	2000	Max flush interval
config.createTable	boolean	true	Auto-create table
config.useJsonColumn	boolean	true	Use JSONB for data
config.ssl	boolean	true	Use SSL

Console

Option	Type	Default	Description
config.format	"pretty" | "json"	"pretty"	Output format
config.level	string	"all"	Event filter: all, sandbox, exec, agent, error
config.includeTimestamp	boolean	true	Show timestamps
config.colorize	boolean	true	Use colors

Event Filter

All exporters support these filter options:

Option	Type	Default	Description
filter.types	string[]	["*"]	Event type patterns (* wildcard)
filter.condition	function	—	Custom filter function
filter.minLevel	"debug" | "info" | "warn" | "error"	—	Minimum event level

---

Provider-Specific Configuration

Runra Sandbox (Hosted)

sandbox: {
  provider: "runra-sandbox",
  apiKey: "rra_live_...",
  apiUrl: "https://api.box.runra.dev",      // optional
}

CubeSandbox (Self-Hosted)

sandbox: {
  provider: "cubesandbox",
  config: {
    masterUrl: "https://cube-master.internal:3000",
    masterToken: "cube-token",
    templates: {
      node: "template-node-22",
      python: "template-python-312",
    },
    nodeSelector: { zone: "us-east-1" },
  },
}

Docker

sandbox: {
  provider: "docker",
  config: {
    socketPath: "/var/run/docker.sock",
    // host: "tcp://192.168.1.100:2375",
    images: {
      node: "node:22-alpine",
      python: "python:3.12-slim",
    },
    networkMode: "bridge",
    autoRemove: true,
  },
}

E2B

sandbox: {
  provider: "e2b",
  config: {
    apiKey: "e2b_...",
    domain: "e2b.dev",     // optional
    template: "base",
  },
}

Next Steps

• SDK Reference — complete TypeScript API
• CLI Reference — terminal commands
• Quick Start — get running in minutes
• Runtime Architecture — understand the stack