Instances - in10nt

Overview

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

Create Instance

Static method (zero-config)

import { Instance } from '@in10nt/sdk';

const instance = await Instance.create({
  name: 'my-agent',
  description: 'My coding agent',
  agentType: 'opencode',              // 'opencode' or 'moltbot'
  containerTemplateId: 'tmpl_12345',   // Optional: custom template
  vmSize: 'shared-cpu-4x',            // Optional: VM size
  region: 'iad',                       // Optional: region
  env: { API_KEY: 'secret' }           // Optional: env vars
});

Via client

import { In10ntClient } from '@in10nt/sdk';

const client = new In10ntClient();
const instance = await client.instances.create({
  name: 'my-agent',
  description: 'My coding agent'
});

Agent Types

Type	Description	Min Size
`opencode`	Default agent (OpenCode)	`shared-cpu-1x`
`moltbot`	Moltbot/Clawdbot agent	`shared-cpu-8x` (2GB)

Moltbot requires at least 2GB RAM and automatically upgrades to shared-cpu-8x if needed

Parameters

Parameter	Type	Description
`name`	`string`	Required - Instance name
`description`	`string`	Required - Description
`agentType`	`string`	Agent type: `opencode` or `moltbot` (default: `opencode`)
`containerTemplateId`	`string`	Container template ID
`vmSize`	`string`	VM size (default: `shared-cpu-4x`)
`region`	`string`	Region code (default: `iad`)
`env`	`object`	Environment variables

Response

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

Connect to Existing Instance

const instance = await Instance.connect('inst_abc123');

// Or via client
const instance = await client.instances.get('inst_abc123');
const instance = await client.instances.getByName('my-agent');

Integrations

Connect your agent to external services:

const instance = await client.instances.create({
  name: 'discord-bot',
  description: 'Discord bot agent',
  agentType: 'moltbot',  // Required for Discord
  integrations: ['Discord', 'GitHub'],
  integrationEnv: {
    DISCORD_BOT_TOKEN: 'xxx',
    DISCORD_GUILD_ID: 'xxx',
    DISCORD_CHANNEL_ID: 'xxx',
    GITHUB_TOKEN: 'xxx'
  }
});

Supported Integrations

Integration	Required Env Vars
`Discord`	`DISCORD_BOT_TOKEN`, `DISCORD_GUILD_ID`, `DISCORD_CHANNEL_ID`
`Slack`	`SLACK_BOT_TOKEN`
`GitHub`	`GITHUB_TOKEN`
`Notion`	`NOTION_API_TOKEN`
`Telegram`	`TELEGRAM_BOT_TOKEN`
`Jira`	`JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`
`Voice`	`TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_FROM_NUMBER`

Voice integration supports both Twilio (required) and ElevenLabs (optional). Add ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID for text-to-speech.

Discord integration only works with agentType: 'moltbot'

Update Integrations

await instance.integrations.set({
  integrations: ['GitHub', 'Notion'],
  integrationEnv: { GITHUB_TOKEN: 'new_token' }
});

// Read current integrations
const config = await instance.integrations.get();

List Instances

// Static
const instances = await Instance.list();

// Via client
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 Instance.connect('inst_abc123');
// or
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 (works for both OpenCode and Moltbot):

const result = await instance.run(
  'Build a REST API with user CRUD operations',
  {
    model: 'anthropic/claude-sonnet-4.5',  // Optional
    timeout: 300_000,                       // Optional
    maxTokens: 8000,                        // Optional
    system: 'Custom system prompt'          // Optional
  }
);

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

The same .run() method works for both OpenCode and Moltbot instances. Moltbot instances automatically use optimized internal routing.

Complete Example with All Options

const result = await instance.run(
  'Build a REST API with authentication',
  {
    model: 'anthropic/claude-sonnet-4.5',
    timeout: 300_000,
    pollInterval: 5_000,
    maxPollTime: 120_000,
    healthCheckRetries: 20,
    healthCheckDelay: 3_000,
    waitForHealth: true,
    maxTokens: 8000,
    system: 'You are a senior backend engineer',
    background: false
  }
);

Options

Option	Type	Default	Description
`model`	`string`	`anthropic/claude-sonnet-4.5`	LLM model
`provider`	`string`	`openrouter`	Model provider
`maxTokens`	`number`	-	Max response tokens
`system`	`string`	-	Custom system prompt
`timeout`	`number`	`480000`	Timeout in ms
`pollInterval`	`number`	`2000`	Poll interval in ms
`maxPollTime`	`number`	`600000`	Max poll time in ms
`healthCheckRetries`	`number`	`40`	Health check retry count
`healthCheckDelay`	`number`	`5000`	Delay between health checks in ms
`waitForHealth`	`boolean`	`true`	Wait for health before running
`background`	`boolean`	`false`	Return taskId immediately
`tools`	`array`	-	Custom tools for the agent
`autoTools`	`boolean`	`true`	Enable automatic tool usage

Background Mode

Run a task in the background and poll later:

const { taskId } = await instance.run('Build a web app', { background: true });

// ... do other work ...

// Poll when ready
const result = await instance.tasks.poll(taskId!);
console.log(result.response);

Tasks Namespace

List Tasks

const tasks = await instance.tasks.list();

Get Task Status

const status = await instance.tasks.getStatus(taskId);
// Returns: { status: 'processing' | 'completed' | 'failed', ... }

Poll Task

const result = await instance.tasks.poll(taskId, {
  pollInterval: 2000,    // Check every 2s
  maxPollTime: 600000    // Timeout after 10min
});

Conversation Context

Instance maintains conversation history automatically. You can send multiple prompts:

const instance = await Instance.create({
  name: 'web-builder',
  description: 'Web project'
});

// 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"

Execute Command

Run a command directly on the instance:

const output = await instance.execute('ls -la /workspace');

Refresh Status

Update instance data:

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

Stop Instance

await instance.stop();

Restart Instance

await instance.restart();

Destroy Instance

await instance.destroy();

Destroy is permanent. Use stop() if you plan to restart later.

Files Namespace

Get Changes

Get files modified by the agent:

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

Filesystem Tree

const tree = await instance.files.tree();

Ports Namespace

Access dev servers running in your instance:

// List active ports
const ports = await instance.ports.list();

// Get proxy URL for a port
const url = instance.ports.getProxyUrl(5173);
// or shorthand
const url = instance.getProxyUrl(5173);

// Register ports manually
await instance.ports.open([5173, 3000, 8080]);

Tools Namespace

// List available tools
const tools = await instance.tools.list();

// Get MCP config
const mcp = await instance.tools.getMcpConfig();

Integrations Namespace

// Get current integrations
const config = await instance.integrations.get();

// Set / update integrations
await instance.integrations.set({
  integrations: ['GitHub'],
  integrationEnv: { GITHUB_TOKEN: 'xxx' }
});

Snapshots

Save and restore workspace state:

// Create snapshot
const { snapshotId } = await instance.snapshot();

// Restore from snapshot (via create with snapshotId)
const restored = await Instance.create({
  name: 'restored',
  description: 'Restored workspace'
});

Save & Clone Instance

Clone from saved templates (workspace snapshots):

// Snapshot an instance
await instance.snapshot();

// List saved templates
const saved = await client.savedTemplates.list();

// Clone from saved template
const clone = await client.instances.createFromSavedTemplate({
  templateName: 'my-template',
  newInstanceName: 'new-instance'
});

// Delete a saved template
await client.savedTemplates.delete('old-template');

Stream Logs

// Node.js: install 'eventsource' package first
const stopStreaming = await instance.streamLogs((log) => {
  console.log(`[${log.type}] ${log.message}`);
});

await instance.run('Build a web app');
stopStreaming();

Quick Examples

Basic Usage

const instance = await Instance.create({
  name: 'my-agent',
  description: 'Quick task'
});

await instance.run('Create a REST API');
await instance.destroy();

Multi-Step Session

const instance = await Instance.create({
  name: 'session',
  description: 'Multi-step project'
});

await instance.run('Initialize project');
await instance.run('Add authentication');
await instance.run('Write tests');

const changes = await instance.files.getChanges();
await instance.destroy();

Discord Bot (Moltbot)

const bot = await client.instances.create({
  name: 'discord-bot',
  description: 'My Discord bot',
  agentType: 'moltbot',
  integrations: ['Discord'],
  integrationEnv: {
    DISCORD_BOT_TOKEN: process.env.DISCORD_TOKEN,
    DISCORD_GUILD_ID: '123456',
    DISCORD_CHANNEL_ID: '789012'
  }
});

// Bot automatically responds to Discord messages
// You can also run tasks directly via HTTP:
await bot.run('Add a /help command that lists all available features');

Voice Agent (Twilio + ElevenLabs)

const voiceAgent = await client.instances.create({
  name: 'voice-assistant',
  description: 'Voice-enabled AI agent',
  integrations: ['Voice'],
  integrationEnv: {
    TWILIO_ACCOUNT_SID: process.env.TWILIO_ACCOUNT_SID,
    TWILIO_AUTH_TOKEN: process.env.TWILIO_AUTH_TOKEN,
    TWILIO_FROM_NUMBER: '+1234567890',
    ELEVENLABS_API_KEY: process.env.ELEVENLABS_KEY,
    ELEVENLABS_VOICE_ID: 'voice_id_here'
  }
});

Moltbot with Custom Options

const moltbot = await client.instances.create({
  name: 'custom-moltbot',
  description: 'Moltbot with custom settings',
  agentType: 'moltbot'
});

// Run task with custom options (same API as OpenCode)
const result = await moltbot.run(
  'Analyze this codebase and suggest improvements',
  {
    model: 'anthropic/claude-sonnet-4.5',
    maxTokens: 16000,
    timeout: 900000  // 15 minutes for complex tasks
  }
);

HTTP API Reference

Base URL: https://in10t-api-v2.fly.dev Auth: Authorization: Bearer YOUR_API_KEY or X-API-Key: YOUR_API_KEY

Create Instance

curl -X POST https://in10t-api-v2.fly.dev/instances \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "description": "My coding agent",
    "agentType": "opencode",
    "region": "iad",
    "vmSize": "shared-cpu-4x"
  }'

List Instances

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://in10t-api-v2.fly.dev/instances

Get Instance

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://in10t-api-v2.fly.dev/instances/{instanceId}

Run Task (OpenCode & Moltbot)

curl -X POST https://in10t-api-v2.fly.dev/instances/{instanceId}/run \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Build a REST API with user CRUD",
    "model": "anthropic/claude-sonnet-4.5",
    "timeout": 480000,
    "max_tokens": 8000
  }'

Body Param	Type	Required	Description
`prompt`	string	Yes	Task prompt
`model`	string	No	LLM model (default: anthropic/claude-sonnet-4.5)
`provider`	string	No	Model provider (default: openrouter)
`timeout`	number	No	Timeout in ms (default: 480000)
`max_tokens`	number	No	Max response tokens
`system`	string	No	Custom system prompt
`async`	boolean	No	Run asynchronously

Stop Instance

curl -X POST https://in10t-api-v2.fly.dev/instances/{instanceId}/stop \
  -H "Authorization: Bearer YOUR_API_KEY"

Destroy Instance

curl -X DELETE https://in10t-api-v2.fly.dev/instances/{instanceId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Restart Instance

curl -X POST https://in10t-api-v2.fly.dev/instances/{instanceId}/restart \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Health

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://in10t-api-v2.fly.dev/instances/{instanceId}/health

Get Changes

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://in10t-api-v2.fly.dev/instances/{instanceId}/changes"

Execute Command

curl -X POST https://in10t-api-v2.fly.dev/instances/{instanceId}/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -la /workspace"}'

Create Snapshot

curl -X POST https://in10t-api-v2.fly.dev/instances/{instanceId}/snapshot \
  -H "Authorization: Bearer YOUR_API_KEY"

List Ports

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://in10t-api-v2.fly.dev/instances/{instanceId}/ports

Open Ports

curl -X POST https://in10t-api-v2.fly.dev/instances/{instanceId}/open-ports \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ports": [5173, 3000]}'

List Tasks

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://in10t-api-v2.fly.dev/instances/{instanceId}/tasks

Get Task Status

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://in10t-api-v2.fly.dev/instances/{instanceId}/tasks/{taskId}

Getting Started

API Reference

Guides

Advanced

​Overview

​Create Instance

​Static method (zero-config)

​Via client

​Agent Types

​Parameters

​Response

​Connect to Existing Instance

​Integrations

​Supported Integrations

​Update Integrations

​List Instances

​Get Instance

​Run Task

​Complete Example with All Options

​Options

​Background Mode

​Tasks Namespace

​List Tasks

​Get Task Status

​Poll Task

​Conversation Context

​Instance Management

​Health Check

​Execute Command

​Refresh Status

​Stop Instance

​Restart Instance

​Destroy Instance

​Files Namespace

​Get Changes

​Filesystem Tree

​Ports Namespace

​Tools Namespace

​Integrations Namespace

​Snapshots

​Save & Clone Instance

​Stream Logs

​Quick Examples

​Basic Usage

​Multi-Step Session

​Discord Bot (Moltbot)

​Voice Agent (Twilio + ElevenLabs)

​Moltbot with Custom Options

​HTTP API Reference

​Create Instance

​List Instances

​Get Instance

​Run Task (OpenCode & Moltbot)

​Stop Instance

​Destroy Instance

​Restart Instance

​Get Health

​Get Changes

​Execute Command

​Create Snapshot

​List Ports

​Open Ports

​List Tasks

​Get Task Status

Overview

Create Instance

Static method (zero-config)

Via client

Agent Types

Parameters

Response

Connect to Existing Instance

Integrations

Supported Integrations

Update Integrations

List Instances

Get Instance

Run Task

Complete Example with All Options

Options

Background Mode

Tasks Namespace

List Tasks

Get Task Status

Poll Task

Conversation Context

Instance Management

Health Check

Execute Command

Refresh Status

Stop Instance

Restart Instance

Destroy Instance

Files Namespace

Get Changes

Filesystem Tree

Ports Namespace

Tools Namespace

Integrations Namespace

Snapshots

Save & Clone Instance

Stream Logs

Quick Examples

Basic Usage

Multi-Step Session

Discord Bot (Moltbot)

Voice Agent (Twilio + ElevenLabs)

Moltbot with Custom Options

HTTP API Reference

Create Instance

List Instances

Get Instance

Run Task (OpenCode & Moltbot)

Stop Instance

Destroy Instance

Restart Instance

Get Health

Get Changes

Execute Command

Create Snapshot

List Ports

Open Ports

List Tasks

Get Task Status