Scalability

Load Increases          Load Decreases
      │                       │
      ▼                       ▼
┌─────────────┐         ┌─────────────┐
│ CPU > 70%   │         │ CPU < 30%   │
│ for 60s     │         │ for 120s    │
└──────┬──────┘         └──────┬──────┘
       │                       │
       ▼                       ▼
┌─────────────┐         ┌─────────────┐
│ Add         │         │ Remove      │
│ Instance    │         │ Instance    │
└─────────────┘         └─────────────┘

Request Flow - Cold Start:
[Request] → [Start Container] → [Mount Storage] → [Execute] → [Response]
              ~3-5 seconds        ~1 second         varies

Request Flow - Warm Container:
[Request] → [Execute] → [Response]
             ~100ms

HTTP/1.1 429 Too Many Requests
Retry-After: 60
 
{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Retry after 60 seconds.",
  "retryAfter": 60
}

import { ComputerAgentsClient, ApiClientError } from 'computer-agents';
 
async function executeWithRetry(task: string, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.run(task, { environmentId: 'env_xxx' });
    } catch (error) {
      if (error instanceof ApiClientError && error.status === 429) {
        const retryAfter = error.retryAfter || 60;
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

// Good: Reuse environment
const env = await client.environments.getDefault();
await client.run(task1, { environmentId: env.id });
await client.run(task2, { environmentId: env.id }); // Warm container!
 
// Less optimal: New environment each time
await client.run(task1, { environmentId: (await client.environments.create({})).id });

// Good: Related tasks in same thread
const r1 = await client.run('Create project structure', { environmentId });
const r2 = await client.run('Add tests', { threadId: r1.threadId }); // Context preserved!
 
// Less optimal: Separate threads
const r1 = await client.run('Create project structure', { environmentId });
const r2 = await client.run('Add tests to the project structure I just created', { environmentId });

try {
  await client.run(task, options);
} catch (error) {
  if (error.status === 429) {
    // Rate limited - back off and retry
  } else if (error.status === 402) {
    // Budget exhausted - notify user
  } else if (error.status >= 500) {
    // Server error - retry with exponential backoff
  }
}

// Check budget before batch operations
const budget = await client.budget.get();
 
if (budget.balance < estimatedCost) {
  console.log('Insufficient budget for operation');
  return;
}
 
// Proceed with operations
for (const task of tasks) {
  await client.run(task, options);
}