Connecting to Containers

Agents that run locally can move to TestBase Cloud without code changes. Configure a container, hand the resulting client to your agent, and the SDK handles the rest.

1. Create a container

Use the Cloud SDK (@testbase/cloud) for typed helpers:


import { TestbaseCloud } from '@testbase/cloud';
 
const cloud = new TestbaseCloud({
  apiKey: process.env.TESTBASE_API_KEY,
  apiUrl: process.env.TESTBASE_API_URL,      // optional (defaults to https://api.testbase.dev)
  defaultRegion: 'us-central1',
  debug: true
});
 
const cloudAgent = await cloud.createCloudAgent({
  name: 'Cloud Worker',
  agentType: 'worker',
  workspace: './workspace',
  model: 'gpt-4o-mini',
  reasoningEffort: 'low',
  persistContainer: false,                   // or true for long-lived environments
  mcpServers: []
});

createCloudAgent provisions a container, returns the agent plus metadata (containerId, cloudRunServiceUrl), and wires up a ready-to-use runtime configuration.

Prefer raw API calls? POST to /api/v1/containers with the same fields and create the Agent manually using cloud.forContainer(id, url).

2. Run tasks exactly as before


import { run } from 'computer-agents';
 
const result = await run(cloudAgent, 'Implement rate limiting for the API');
console.log(result.finalOutput);

run streams output, artefacts, and errors the same way it does locally. If the container becomes unhealthy, the SDK raises a typed error that includes log URLs for debugging.

3. Manage the container lifecycle


// Upload seed files
await cloud.uploadFile(cloudAgent.containerId, '/workspace/.env', 'SECRET=1');
 
// Update configuration mid-flight
await cloud.updateContainer(cloudAgent.containerId, {
  model: 'gpt-5-mini',
  reasoningEffort: 'medium'
});
 
// Check health and logs
const health = await cloud.getHealth(cloudAgent.containerId);
if (!health.healthy) {
  console.log(await cloud.getLogs(cloudAgent.containerId, 200));
}
 
// Tear down when done
await cloud.deleteContainer(cloudAgent.containerId);

The SDK exposes typed errors (ContainerNotFoundError, AuthenticationError, etc.) so you can branch on failure conditions.

Reusing containers

Persistent (persistContainer: true): reuse the same environment across tasks, ideal for iterative development or long-running monitoring. Workspaces remain mounted until you delete the container.
Ephemeral: default behaviour. Suitable for CI/CD jobs or single-shot tasks. Artefacts stay in GCS even after the container is deleted.


const persistent = await cloud.createCloudAgent({
  name: 'Persistent Worker',
  agentType: 'worker',
  workspace: './repo',
  persistContainer: true
});
 
await run(persistent, 'Add feature A');
await run(persistent, 'Write tests for feature A');
 
// when finished
await cloud.deleteContainer(persistent.containerId);

Hybrid workflows

You can mix local planners with cloud workers, or vice versa. The Agents SDK treats all agents uniformly, so orchestrators can coordinate across execution modes.


const planner = new Agent({
  name: 'Local Planner',
  agentType: 'planner',
  workspace: './repo'
});
 
const plan = await run(planner, 'Design the authentication module');
 
await run(cloudAgent, `Follow this plan:
${plan.finalOutput}`);

The main rule: ensure both agents point at compatible workspaces. Sync commits between local and cloud via git or the Files API to prevent drift.