Configuration Cheat Sheet

Use this page to find the knobs you’ll set most often when working with TestBase.

Environment variables

Variable	Used by	Purpose
`TESTBASE_API_KEY`	Cloud SDK / Cloud API	API key (`tb_{env}_{id}`) for container + file operations.
`TESTBASE_API_URL`	Cloud SDK	Base URL for the Cloud API (default `https://api.testbase.dev`).
`OPENAI_API_KEY`	Cloud API / containers	Auth for Codex CLI inside containers.
`TESTBASE_SESSION_DIR`	CLI	Override location where session artefacts are stored.
`BRAVE_API_KEY`, `NOTION_TOKEN`, etc.	MCP servers	Tool-specific credentials injected via MCP `env` or `bearerToken`.

Agents SDK configuration


new Agent({
  name: 'Worker',
  agentType: 'worker',            // llm | worker | planner | reviewer | orchestrator
  workspace: './repo',            // required for Codex roles
  codexModel: 'gpt-4o-mini',
  codexReasoningEffort: 'medium', // none | low | medium | high
  codexMcpServers: [...],         // optional MCP definitions
  runtime: {
    executionMode: 'cloud',
    client: cloud.forContainer(id, url)
  }
});

Cloud SDK defaults


new TestbaseCloud({
  apiKey: process.env.TESTBASE_API_KEY, // required
  apiUrl: 'https://api.testbase.dev',   // default
  defaultRegion: 'us-central1',        // optional
  defaultTimeout: 300000,              // milliseconds
  debug: false                         // set true for verbose logging
});

Cloud API endpoints

Endpoint	Purpose
`POST /api/v1/containers`	Create container
`GET /api/v1/containers`	List containers
`PATCH /api/v1/containers/:id`	Update model/reasoning
`DELETE /api/v1/containers/:id`	Tear down container
`POST /api/v1/containers/:id/mcp-servers`	Add MCP server
`DELETE /api/v1/containers/:id/mcp-servers/:name`	Remove MCP server
`GET /api/v1/containers/:id/files`	List workspace files
`GET /api/v1/containers/:id/files/download`	Download file
`PUT /api/v1/containers/:id/files`	Upload/overwrite file
`DELETE /api/v1/containers/:id/files`	Delete file
`GET /api/v1/containers/:id/logs`	Retrieve logs
`GET /api/v1/containers/:id/health`	Check status

CLI helpers

Command	Description
`node ./bin/start-session.mjs --repo <path> --task "<text>"`	Launch planner/worker/reviewer locally.
`npm run mcp:orchestrator`	Expose orchestrator MCP server via STDIO.
`npm run mcp:worker`	Expose worker MCP server.

Docker image settings

Build arguments in testbase-cloud/docker/Dockerfile control base Node version and package cache. Update entrypoint.sh to tweak sync intervals or boot hooks.

Timeouts

Container creation timeout: configurable per request (timeout parameter, default 300,000 ms).
MCP startup timeout: startupTimeoutSec (default 30).
MCP tool timeout: toolTimeoutSec (default 60).
Cloud SDK requests: defaultTimeout in the client config.

Keep this sheet handy when setting up new environments or rotating secrets.