Get Started with Testbase

This quickstart guide will have you running your first computer agent in under a minute. We’ll create a simple agent, execute a task, and see how session continuity works automatically.

Prerequisites

Node.js 18+
OpenAI API key
A git repository to work in (required for computer agents)

Installation


cd computer-agents
pnpm install
pnpm build

Your first agent (30 seconds)

1. Set your API key


export OPENAI_API_KEY=sk-...

2. Create a basic computer agent

Create a file called my-first-agent.mjs:


import { Agent, run, LocalRuntime } from 'computer-agents';
 
const agent = new Agent({
  name: 'Developer',
  agentType: 'computer',
  runtime: new LocalRuntime({
    debug: true  // See execution details
  }),
  workspace: './my-project',  // Must be a git repo
  instructions: 'You are a software developer. Write clean, well-documented code.'
});
 
// Execute a task
const result = await run(agent, 'Create a Python script called greet.py that prints Hello World');
 
console.log('Result:', result.finalOutput);
console.log('Session ID:', agent.currentThreadId);

3. Run it


node my-first-agent.mjs

You’ll see the agent:

Analyze the task
Create the file
Return a summary of what it did

Session continuity (automatic!)

One of Testbase’s key features is automatic session continuity. Multiple run() calls on the same agent continue the conversation:


// First task - new session
await run(agent, 'Create hello.py');
 
// Second task - continues the same session!
await run(agent, 'Add a main() function');
 
// Third task - still the same session!
await run(agent, 'Add error handling');
 
console.log(agent.currentThreadId);  // Same ID throughout
 
// Start fresh when needed
agent.resetSession();
await run(agent, 'New project');  // New session

Agent types

Testbase has two agent types:

Computer agents (agentType: 'computer'):

Execute via Codex SDK
Can read/write files, run commands, execute code
Require a runtime (LocalRuntime or CloudRuntime)
Must have a workspace (git repository)

LLM agents (agentType: 'llm'):

Execute via OpenAI API
Good for planning, analysis, review
No runtime needed
No workspace required

Example LLM agent


import { Agent, run } from 'computer-agents';
 
const planner = new Agent({
  name: 'Planner',
  agentType: 'llm',
  model: 'gpt-4o',
  instructions: 'Create detailed implementation plans.'
});
 
const plan = await run(planner, 'Plan: Build a REST API for user management');
console.log(plan.finalOutput);

Multi-agent workflows

Combine LLM and computer agents for sophisticated workflows:


import { Agent, run, LocalRuntime } from 'computer-agents';
 
// LLM agent creates the plan
const planner = new Agent({
  agentType: 'llm',
  model: 'gpt-4o',
  instructions: 'Create implementation plans.'
});
 
// Computer agent executes the plan
const executor = new Agent({
  agentType: 'computer',
  runtime: new LocalRuntime(),
  workspace: './project',
  instructions: 'Execute implementation plans.'
});
 
// LLM agent reviews the result
const reviewer = new Agent({
  agentType: 'llm',
  model: 'gpt-4o',
  instructions: 'Review code for quality and correctness.'
});
 
// Run the workflow
const task = 'Create a Python calculator with tests';
const plan = await run(planner, `Plan: ${task}`);
const implementation = await run(executor, plan.finalOutput);
const review = await run(reviewer, `Review: ${implementation.finalOutput}`);
 
console.log('Review:', review.finalOutput);

Running examples

The repository includes several ready-to-run examples:


cd computer-agents/examples/testbase
 
# Basic computer agent (local)
node basic-computer-agent.mjs
 
# Cloud execution (requires API key)
TESTBASE_API_KEY=your_key node computer-agent-cloud.mjs
 
# Multi-agent workflow
node multi-agent-workflow.mjs
 
# Session continuity demo
node hello-world.mjs

Common issues

”Runtime required for computer agents”

Computer agents need a runtime. Add:


runtime: new LocalRuntime()

“Not a git repository”

Codex SDK requires the workspace to be a git repository for safety:


cd my-project
git init
git add .
git commit -m "Initial commit"

Or skip the check (not recommended):


skipGitRepoCheck: true

“OPENAI_API_KEY not set”

Export your OpenAI API key:


export OPENAI_API_KEY=sk-...

What’s next?

Architecture - Understand how agents and runtimes work together
Agents SDK - Dive into agent configuration and advanced patterns
Cloud Platform - Learn about cloud execution with billing
Quick Start Guide - More examples and troubleshooting

Full configuration reference


const agent = new Agent({
  // Required
  name: string;
  agentType: 'llm' | 'computer';
 
  // Computer agents only
  runtime?: LocalRuntime | CloudRuntime;  // Required for 'computer'
  workspace?: string;  // Required for 'computer'
 
  // LLM agents only
  model?: string;  // e.g. 'gpt-4o', 'gpt-4o-mini'
  tools?: ToolDefinition[];
 
  // Optional for all
  instructions?: string;
  mcpServers?: McpServerConfig[];  // Unified MCP config
  reasoningEffort?: 'none' | 'low' | 'medium' | 'high';
  temperature?: number;
  maxTokens?: number;
});

You’re ready to build! Start with the examples and explore from there.