Production Setup

This guide covers everything you need to configure Runra Sandbox for production workloads. Follow these steps to ensure reliable, secure, and cost-effective sandbox operations.

API key management

Creating an API key

API keys are managed through the Runra Dashboard. Each key is scoped to an organization and can have fine-grained permissions.

# Always load your API key from environment variables
export RUNRA_API_KEY="rsk_live_xxxxxxxxxxxxxxxxxxxx"

Key best practices

• Use separate keys per environment: Dev, staging, and production should each have their own API key.
• Rotate keys regularly: Generate new keys and deactivate old ones on a schedule.
• Never commit keys: Use a secrets manager or environment variables.
• Scope keys by sandbox type: Create restricted keys that can only create sandboxes with specific resources.

Multiple API keys

If you manage sandboxes for different applications or tenants, use separate Runra clients:

const appA = new Runra({
  sandbox: { provider: "runra-sandbox", apiKey: process.env.APP_A_KEY },
});

const appB = new Runra({
  sandbox: { provider: "runra-sandbox", apiKey: process.env.APP_B_KEY },
});

Environment configuration

Required variables

Variable	Description	Example
RUNRA_API_KEY	Your Runra API key	rsk_live_...
RUNRA_API_URL	API base URL	https://api.box.runra.dev

Recommended variables

Variable	Description	Example
RUNRA_DEFAULT_IMAGE	Default sandbox image	node:22
RUNRA_DEFAULT_CPU	Default CPU allocation	2
RUNRA_DEFAULT_MEMORY_MB	Default memory allocation	4096
RUNRA_DEFAULT_TIMEOUT_MS	Default sandbox timeout	300000

Programmatic configuration

Prefer programmatic configuration for more control:

import { Runra } from "@runra/sdk";

const runra = new Runra({
  sandbox: {
    provider: "runra-sandbox",
    apiKey: process.env.RUNRA_API_KEY!,
    apiUrl: process.env.RUNRA_API_URL ?? "https://api.box.runra.dev",
    defaults: {
      image: "node:22",
      resources: {
        cpu: 2,
        memoryMb: 4096,
        diskMb: 10240,
      },
      timeoutMs: 300_000,
      idleTimeoutMs: 120_000,
    },
  },
  observability: {
    provider: "axiom",
    token: process.env.AXIOM_TOKEN,
    dataset: "runra-production",
  },
});

Resource planning

Sizing guidelines

Choose resources based on your workload:

Workload	CPU	Memory	Disk	Typical use
Light scripting	2	2048 MB	5120 MB	Simple scripts, API calls
Web development	2	4096 MB	10240 MB	npm install, build, test
Data processing	4	8192 MB	20480 MB	Python data pipelines
Full-stack agent	4	8192 MB	20480 MB	Claude Code, Codex agents
Heavy ML/compilation	8	16384 MB	51200 MB	Model training, large builds

Estimating concurrency

This is the most important production planning step. Determine your peak concurrent sandbox count:

concurrent_sandboxes = peak_requests_per_second × average_sandbox_lifetime_seconds

Example: If you handle 5 agent requests per second, each lasting 120 seconds on average:

5 req/s × 120s = 600 concurrent sandboxes

Capacity tiers

Tier	Max concurrent sandboxes	Suitable for
Starter	50	Prototyping, small teams
Pro	500	Production SaaS applications
Enterprise	Custom	High-scale platforms

Contact sales@runra.dev to discuss enterprise capacity.

Concurrency limits

Client-side rate limiting

Implement exponential backoff to handle rate limits gracefully:

async function createSandboxWithRetry(
  runra: Runra,
  config: SandboxConfig,
  maxRetries = 5
): Promise<Sandbox> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await runra.sandboxes.create(config);
    } catch (error) {
      if (error.code === "RATE_LIMITED" && attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
        console.warn(`Rate limited. Retrying in ${delay}ms...`);
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error("Max retries exceeded");
}

Concurrency pools

Manage a pool of available sandboxes for better performance:

class SandboxPool {
  private available: Sandbox[] = [];
  private inUse = new Set<string>();

  constructor(
    private runra: Runra,
    private poolSize: number,
    private config: SandboxConfig
  ) {}

  async initialize() {
    this.available = await Promise.all(
      Array.from({ length: this.poolSize }, () =>
        this.runra.sandboxes.create(this.config)
      )
    );
  }

  async acquire(): Promise<Sandbox> {
    if (this.available.length === 0) {
      // Pool exhausted — create on demand
      return this.runra.sandboxes.create(this.config);
    }
    const sandbox = this.available.pop()!;
    this.inUse.add(sandbox.id);
    return sandbox;
  }

  async release(sandbox: Sandbox) {
    this.inUse.delete(sandbox.id);
    // Reset sandbox to clean state
    await sandbox.exec("rm -rf /workspace/*");
    this.available.push(sandbox);
  }
}

// Usage
const pool = new SandboxPool(runra, 20, {
  image: "node:22",
  resources: { cpu: 2, memoryMb: 4096 },
});
await pool.initialize();

// Acquire and release during request handling
const sandbox = await pool.acquire();
try {
  await sandbox.exec("npm test");
} finally {
  await pool.release(sandbox);
}

Template selection

Available templates

Runra provides pre-built templates for common environments:

// Use a named template
const sandbox = await runra.sandboxes.create({
  template: "node-typescript",
});

// Or specify an image directly
const sandbox = await runra.sandboxes.create({
  image: "node:22",
});

Common templates

Template	Image	Includes
node-basic	node:22	Node.js 22, npm, npx
node-typescript	node:22	Node.js + TypeScript, ts-node, tsx
python-basic	python:3.12	Python 3.12, pip
python-ml	python:3.12	Python + numpy, pandas, scikit-learn
fullstack	node:22	Node.js + Python + git + curl
ubuntu-base	ubuntu:24.04	Clean Ubuntu with build-essential

Custom templates

For custom environments, use a Dockerfile and specify the image:

const sandbox = await runra.sandboxes.create({
  image: "my-registry/my-custom-image:latest",
  // Custom images must be pre-loaded; contact support for setup
});

Error handling

Common errors

Error code	Description	Action
RATE_LIMITED	Too many requests	Implement backoff
RESOURCE_EXHAUSTED	No capacity available	Retry or reduce concurrency
INVALID_CONFIG	Bad sandbox configuration	Check your create options
SANDBOX_TIMEOUT	Sandbox exceeded timeout	Increase timeout or optimize workload
IMAGE_NOT_FOUND	Template/image doesn’t exist	Verify image name
QUOTA_EXCEEDED	Account quota hit	Upgrade plan or terminate idle sandboxes

Graceful degradation

async function safeCreateSandbox(config: SandboxConfig): Promise<Sandbox | null> {
  try {
    return await runra.sandboxes.create(config);
  } catch (error) {
    switch (error.code) {
      case "RESOURCE_EXHAUSTED":
        // Try a smaller sandbox
        return runra.sandboxes.create({
          ...config,
          resources: { cpu: 2, memoryMb: 2048 },
        });
      case "RATE_LIMITED":
        // Queue for later
        await enqueueSandboxRequest(config);
        return null;
      default:
        throw error;
    }
  }
}

Next steps

• Running Code — execute commands in sandboxes
• Observability — monitor production sandbox usage
• SDK Usage — full SDK reference