Skip to content
Runra Sandbox Docs

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

Section titled “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

Section titled “Config File”

Location

Section titled “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

Section titled “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

Section titled “Environment Variables”

Core

Section titled “Core”
VariableTypeDefaultDescription
RUNRA_API_KEYstring—Runra Sandbox API key
RUNRA_API_URLstringhttps://api.box.runra.devAPI base URL
RUNRA_LOG_LEVELstringinfoLog level: debug, info, warn, error
RUNRA_CONFIG_PATHstring—Override config file path

Sandbox

Section titled “Sandbox”
VariableTypeDefaultDescription
RUNRA_SANDBOX_PROVIDERstringrunra-sandboxSandbox provider
RUNRA_SANDBOX_IMAGEstringnode:22Default sandbox image
RUNRA_SANDBOX_CPUnumber2Default vCPUs
RUNRA_SANDBOX_MEMORY_MBnumber4096Default memory in MB
RUNRA_SANDBOX_DISK_MBnumber10240Default disk in MB
RUNRA_SANDBOX_TIMEOUT_MSnumber300000Default sandbox timeout
RUNRA_SANDBOX_IDLE_TIMEOUT_MSnumber120000Default idle timeout

Agent

Section titled “Agent”
VariableTypeDefaultDescription
RUNRA_AGENT_PROVIDERstringclaude-codeAgent adapter
RUNRA_AGENT_MODELstring—Agent model override
RUNRA_AGENT_MAX_TURNSnumber50Max agent loops
RUNRA_AGENT_PERMISSION_MODEstringauto-approvePermission mode

LLM Providers

Section titled “LLM Providers”
VariableTypeDefaultDescription
OPENAI_API_KEYstring—OpenAI API key
ANTHROPIC_API_KEYstring—Anthropic API key
GEMINI_API_KEYstring—Gemini API key
OPENROUTER_API_KEYstring—OpenRouter API key
RUNRA_LLM_PROVIDERstring—LLM provider override
RUNRA_LLM_MODELstring—LLM model override
RUNRA_LLM_TEMPERATUREnumber0.3Temperature (0.0–2.0)
RUNRA_LLM_MAX_TOKENSnumber4096Max tokens per response
RUNRA_LLM_TIMEOUT_MSnumber30000Request timeout

Observability

Section titled “Observability”
VariableTypeDefaultDescription
AXIOM_TOKENstring—Axiom API token
AXIOM_DATASETstringrunra-eventsAxiom dataset name
AXIOM_URLstringhttps://cloud.axiom.coAxiom deployment URL
OTEL_EXPORTER_OTLP_ENDPOINTstring—OTLP endpoint
OTEL_EXPORTER_OTLP_HEADERSstring—OTLP headers (key=value,…)
OTEL_SERVICE_NAMEstringrunra-runtimeOTel service name
DATABASE_URLstring—Postgres connection string (for exporter)

CubeSandbox (Self-Hosted)

Section titled “CubeSandbox (Self-Hosted)”
VariableTypeDefaultDescription
CUBE_MASTER_URLstring—CubeMaster API URL
CUBE_MASTER_TOKENstring—CubeMaster auth token
CUBE_TEMPLATE_NODEstring—Node.js template name
CUBE_TEMPLATE_PYTHONstring—Python template name

Docker Provider

Section titled “Docker Provider”
VariableTypeDefaultDescription
DOCKER_HOSTstringunix:///var/run/docker.sockDocker socket/host
DOCKER_NETWORK_MODEstringbridgeNetwork mode
DOCKER_AUTO_REMOVEbooleantrueAuto-remove containers

Sandbox Options Reference

Section titled “Sandbox Options Reference”

resources

Section titled “resources”
OptionValuesDefaultDescription
cpu2, 4, 82Virtual CPUs allocated
memoryMb2048–163844096Memory in MB
diskMb5120–5120010240Disk storage in MB

network

Section titled “network”
OptionValuesDefaultDescription
network.egress.default"allow", "deny""allow"Default outbound policy
network.egress.allowstring array—Allowed outbound domains
network.ingress.allowPortsnumber array—Allowed inbound ports

Timing

Section titled “Timing”
OptionMinDefaultMaxDescription
timeoutMs100030000086400000 (24h)Max sandbox lifetime
idleTimeoutMs100001200003600000 (1h)Auto-pause after idle

Images

Section titled “Images”
ImageIncludes
node:22Node.js 22, npm, yarn, pnpm, git, curl, jq
node:20Node.js 20 LTS, same tools
python:3.12Python 3.12, pip, uv, git, curl
python:3.11Python 3.11, same tools
ubuntu:24.04Base Ubuntu 24.04, git, curl, jq, build-essential
ubuntu:22.04Base Ubuntu 22.04, same tools
customBYO image (contact support)

Agent Options Reference

Section titled “Agent Options Reference”
OptionTypeDefaultDescription
providerstring"claude-code"Agent adapter: claude-code, codex, opencode, custom
config.modelstringProvider defaultLLM model for the agent
config.maxTurnsnumber50Maximum agent tool-calling loops
config.allowedToolsstring[]allRestrict available tools
config.permissionMode"auto-approve" | "prompt" | "plan""auto-approve"Tool execution permission mode
config.workdirstring/workspaceAgent working directory
config.systemPromptstring—Override system prompt
config.apiKeystringLLM provider keyAgent-specific API key

Available Tools by Agent

Section titled “Available Tools by Agent”
ToolClaude CodeCodexOpenCode
bash✅✅✅
read✅✅✅
write✅✅✅
edit✅✅✅
glob✅✅✅
grep✅✅✅
task✅—✅
web_search✅——
web_fetch✅——

LLM Provider Options Reference

Section titled “LLM Provider Options Reference”

OpenAI

Section titled “OpenAI”
OptionTypeDefaultDescription
config.apiKeystringOPENAI_API_KEYAPI key
config.baseUrlstringhttps://api.openai.com/v1API endpoint
config.organizationstring—Org ID
config.temperaturenumber0.3Sampling temperature
config.maxTokensnumber4096Max output tokens
config.requestTimeoutMsnumber30000Request timeout

Anthropic

Section titled “Anthropic”
OptionTypeDefaultDescription
config.apiKeystringANTHROPIC_API_KEYAPI key
config.maxTokensnumber8192Max output tokens
config.thinking.typestring—"enabled" for extended thinking
config.thinking.budgetTokensnumber4000Thinking token budget

Gemini

Section titled “Gemini”
OptionTypeDefaultDescription
config.apiKeystringGEMINI_API_KEYAPI key
config.temperaturenumber0.3Sampling temperature
config.maxOutputTokensnumber8192Max output tokens
config.safetySettingsarray—Safety filter settings

OpenRouter

Section titled “OpenRouter”
OptionTypeDefaultDescription
config.apiKeystringOPENROUTER_API_KEYAPI key
config.baseUrlstringhttps://openrouter.ai/api/v1API endpoint
config.appNamestring—Your app name (recommended)
config.headersobject—Additional HTTP headers

Ollama

Section titled “Ollama”
OptionTypeDefaultDescription
config.baseUrlstringhttp://localhost:11434Ollama server URL
config.numCtxnumber32768Context window size

vLLM

Section titled “vLLM”
OptionTypeDefaultDescription
config.baseUrlstringhttp://localhost:8000/v1vLLM server URL
config.apiKeystring—API key (if required)

Observability Exporter Options Reference

Section titled “Observability Exporter Options Reference”

Axiom

Section titled “Axiom”
OptionTypeDefaultDescription
config.tokenstringAXIOM_TOKENAPI or ingest token
config.datasetstring"runra-events"Dataset name
config.urlstring"https://cloud.axiom.co"Axiom URL
config.batchSizenumber100Max events per batch
config.flushIntervalMsnumber5000Max flush interval

OpenTelemetry

Section titled “OpenTelemetry”
OptionTypeDefaultDescription
config.endpointstring—OTLP endpoint
config.protocol"http/protobuf" | "grpc""http/protobuf"Transport protocol
config.headersobject—Request headers
config.serviceNamestring"runra-runtime"Service name
config.serviceVersionstring—Service version
config.spanProcessor"batch" | "simple""batch"Span processing mode
config.batchConfig.maxQueueSizenumber2048Max queue size
config.batchConfig.maxExportBatchSizenumber512Max batch size
config.batchConfig.scheduleDelayMsnumber5000Batch delay

JSONL

Section titled “JSONL”
OptionTypeDefaultDescription
config.filePathstring"./runra-events.jsonl"Output file path
config.appendbooleantrueAppend to existing file
config.rotateSizeBytesnumber104857600 (100 MB)Rotation size
config.rotateFilesnumber10Max rotated files
config.gzipbooleantrueGzip rotated files

Postgres

Section titled “Postgres”
OptionTypeDefaultDescription
config.connectionStringstringDATABASE_URLConnection string
config.tablestring"runra_events"Table name
config.schemastring"public"Schema name
config.batchSizenumber50Max inserts per batch
config.flushIntervalMsnumber2000Max flush interval
config.createTablebooleantrueAuto-create table
config.useJsonColumnbooleantrueUse JSONB for data
config.sslbooleantrueUse SSL

Console

Section titled “Console”
OptionTypeDefaultDescription
config.format"pretty" | "json""pretty"Output format
config.levelstring"all"Event filter: all, sandbox, exec, agent, error
config.includeTimestampbooleantrueShow timestamps
config.colorizebooleantrueUse colors

Event Filter

Section titled “Event Filter”

All exporters support these filter options:

OptionTypeDefaultDescription
filter.typesstring[]["*"]Event type patterns (* wildcard)
filter.conditionfunction—Custom filter function
filter.minLevel"debug" | "info" | "warn" | "error"—Minimum event level

Provider-Specific Configuration

Section titled “Provider-Specific Configuration”

Runra Sandbox (Hosted)

Section titled “Runra Sandbox (Hosted)”
sandbox: {
  provider: "runra-sandbox",
  apiKey: "rra_live_...",
  apiUrl: "https://api.box.runra.dev",      // optional
}

CubeSandbox (Self-Hosted)

Section titled “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

Section titled “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

Section titled “E2B”
sandbox: {
  provider: "e2b",
  config: {
    apiKey: "e2b_...",
    domain: "e2b.dev",     // optional
    template: "base",
  },
}

Next Steps

Section titled “Next Steps”