Skip to main content

​
Overview

Instances are VMs running the in10nt agent server. They provide isolated environments for executing AI coding tasks.

​
Create Instance

Create a new VM instance: 
const instance = await client.instances.create({
  name: 'my-agent',              // Optional: Human-readable name
  description: 'My agent',       // Optional: Description
  templateId: 'tmpl_12345',      // Optional: Use custom template
  vmImage: 'custom:latest',      // Optional: Direct image (overrides template)
  vmSize: 'shared-cpu-4x',       // Optional: VM size
  region: 'iad',                 // Optional: Region code
  env: {                         // Optional: Environment variables
    API_KEY: 'secret'
  }
});

console.log(`Instance ID: ${instance.instanceId}`);
console.log(`Status: ${instance.status}`);
console.log(`Agent URL: ${instance.agentUrl}`);

​
Parameters

ParameterTypeDescription
namestringHuman-readable instance name
descriptionstringInstance description
templateIdstringContainer template ID to use
vmImagestringDirect Docker image (overrides template)
vmSizestringVM size (default: shared-cpu-4x)
regionstringRegion code (default: iad)
envobjectEnvironment variables

​
Response

{
  instanceId: "inst_abc123",
  name: "my-agent",
  status: "running",
  agentUrl: "http://machine-id.vm.app.internal:3000",
  createdAt: "2025-01-06T..."
}

​
List Instances

Get all your instances: 
const instances = await client.instances.list();

instances.forEach(instance => {
  console.log(`${instance.name}: ${instance.status}`);
});

​
Get Instance

Retrieve a specific instance by ID: 
const instance = await client.instances.get('inst_abc123');
Or by name: 
const instance = await client.instances.getByName('my-agent');

​
Run Task

Execute a coding task on an instance: 
const result = await instance.run(
  'Build a REST API with user CRUD operations',
  {
    model: 'anthropic/claude-sonnet-4.5',  // Optional
    provider: 'openrouter',                 // Optional
    timeout: 480000,                        // Optional: 8 minutes
    waitForHealth: true,                    // Optional: Auto health check
    system: 'Custom system prompt'          // Optional
  }
);

console.log(result.response);
console.log(`Tokens used: ${result.tokensUsed}`);
console.log(`Duration: ${result.duration_ms}ms`);

​
Options

OptionTypeDefaultDescription
modelstringanthropic/claude-sonnet-4.5LLM model to use
providerstringopenrouterModel provider
timeoutnumber480000Timeout in milliseconds
waitForHealthbooleantrueAuto health check before running
systemstring-Custom system prompt
toolsarray-Custom tools
autoToolsbooleantrueEnable automatic tool usage
The SDK automatically waits for the instance to be healthy before running tasks when waitForHealth: true

​
Conversation Context

Instance maintains conversation history automatically. You can send multiple prompts: 
const instance = await client.instances.create({ name: 'web-builder' });

// First prompt
await instance.run('Create a simple REST API with user CRUD');

// Follow-up prompts (context maintained)
await instance.run('Add JWT authentication');
await instance.run('Add rate limiting middleware');
await instance.run('Write integration tests');

​
Instance Management

​
Health Check

Check if instance is ready: 
const health = await instance.health();
console.log(health.status); // "healthy"

​
Get Changes

Get files modified by the instance: 
const changes = await instance.getChanges();
console.log('Modified files:', changes.changes);

​
Refresh Status

Update instance data: 
await instance.refresh();
console.log(`Current status: ${instance.status}`);

​
Stop Instance

Stop a running instance: 
await instance.stop();

​
Destroy Instance

Permanently delete an instance: 
await instance.destroy();
Destroying an instance is permanent and cannot be undone

​
Clone Instance

Create a new instance from an existing one (clones workspace and configuration): 
const clone = await client.instances.createFromTemplate({
  templateName: 'base-instance',
  newInstanceName: 'cloned-instance'
});
This is different from container templates - it clones an existing instance’s workspace, files, and configuration

​
Stream Logs

Stream real-time logs from an instance: 
// Requires 'eventsource' package in Node.js
const stopStreaming = await instance.streamLogs((log) => {
  console.log(`[${log.type}] ${log.message}`);
});

// Run task
await instance.run('Build a web application');

// Stop streaming when done
stopStreaming();

​
Example Workflows

​
Quick Task

const instance = await client.instances.create({ name: 'quick-task' });
const result = await instance.run('Create a calculator function');
await instance.destroy();

​
Long-Running Session

const instance = await client.instances.create({ name: 'session' });

try {
  await instance.run('Initialize project structure');
  await instance.run('Add user authentication');
  await instance.run('Write tests');
  
  const changes = await instance.getChanges();
  console.log('All changes:', changes);
} finally {
  await instance.destroy();
}

​
Custom Environment

const instance = await client.instances.create({
  name: 'python-ml',
  templateId: 'tmpl_python_ml',
  env: {
    PYTHONPATH: '/workspace',
    MODEL_VERSION: '2.0'
  }
});

const result = await instance.run('Train a classifier on data.csv');