npm package: @in10nt/sdk
Description: Client SDK for in10t AI Agent VMs
Author: in10t
Latest version: 2.2.0

# In10nt SDK

Client SDK for creating and managing AI agent VMs with custom environments.

## What's New in 2.2.0

🦞 **Agent Type Support** - Create Moltbot/OpenClaw instances with `agentType` parameter
- Support for `opencode`, `moltbot`, `openclaw`, and `clawdbot` agent types
- Automatic normalization: `openclaw` and `clawdbot` are aliased to `moltbot`
- `createFromTemplate()` now preserves the agent type when cloning

## Installation

```bash
npm install @in10nt/sdk
```

## Quick Start

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

const client = new In10ntClient({
  apiKey: process.env.IN10NT_API_KEY
});

// Create an instance
const instance = await client.instances.create({
  name: 'my-agent',
  description: 'General purpose agent'
});

// Run a task
const result = await instance.run('Build a REST API for user management');
console.log(result.response);

// Access web apps started inside the VM
// Use the proxy URL (never localhost):
// https://in10t-api-v2.fly.dev/instances/{instanceId}/ports/{port}/

// Cleanup
await instance.destroy();
```

## Features

- 🚀 **Simple API** - Create instances with one line of code
- 🐳 **Custom Environments** - Build custom Docker images with your tools
- 🦞 **Multiple Agent Types** - Support for OpenCode, Moltbot/OpenClaw, and Clawdbot
- 🔄 **Instance Reuse** - Preserve state across multiple tasks
- 📊 **Usage Tracking** - Monitor token usage and costs
- ⚡ **Async Task Support** - Automatic polling for long-running tasks
- 🔧 **Full TypeScript Support** - Type definitions included

## Core Concepts

### 1. Instances

Instances are running VMs with the agent server:

```javascript
// Create instance
const instance = await client.instances.create({
  name: 'my-agent',
  description: 'Handles data processing',
  region: 'iad',
  vmSize: 'shared-cpu-4x',
  env: {
    API_KEY: 'secret'
  }
});

// List instances
const instances = await client.instances.list();

// Get by ID
const instance = await client.instances.get('inst_abc123');

// Get by name
const instance = await client.instances.getByName('my-agent');

// Create instance from saved template (clone)
const clonedInstance = await client.instances.createFromTemplate({
  templateName: 'my-saved-template',
  newInstanceName: 'my-cloned-agent'
});
```

### Agent Types

In10nt supports multiple agent types. You can specify the agent type when creating an instance:

```javascript
// OpenCode agent (default)
const opencode = await client.instances.create({
  name: 'opencode-agent',
  description: 'Default OpenCode agent',
  agentType: 'opencode' // or omit for default
});

// Moltbot/OpenClaw agent
const moltbot = await client.instances.create({
  name: 'moltbot-agent',
  description: 'Moltbot agent',
  agentType: 'moltbot' // or 'openclaw' or 'clawdbot'
});
```

**Supported agent types:**
- `opencode` - Default agent type (omit agentType to use this)
- `moltbot` - Moltbot agent (also accepts `openclaw` or `clawdbot` as aliases)

**Note:** The SDK automatically normalizes `openclaw` and `clawdbot` to `moltbot` when sending to the API.

### Accessing Web Apps (Ports)

If the agent starts a server (e.g. Vite on 5173 or API on 3000), access it through the proxy:

```
https://in10t-api-v2.fly.dev/instances/{instanceId}/ports/{port}/
```

You can list detected ports:

```javascript
const ports = await client.client.get(`/instances/${instance.instanceId}/ports`);
console.log(ports.data.ports);
```

If a port isn't showing, you can manually register it:

```javascript
await client.client.post(`/instances/${instance.instanceId}/open-ports`, { ports: [5173] });
```

### 2. Container Templates (Optional)

Create custom environments with your own Docker images:

```javascript
// Create template
const template = await client.templates.create({
  name: 'python-ml',
  image: 'python:3.11-slim',
  registryType: 'dockerhub',
  description: 'Python with ML libraries'
});

// Wait for build
await template.waitUntilReady();

// Use template
const instance = await client.instances.create({
  templateId: template.templateId
});
```

### 2.5. Creating from Saved Templates

Clone existing instances from saved templates. This is useful for creating new instances with the same configuration, environment variables, and workspace state as a previously saved instance:

```javascript
// Create a new instance from a saved template
const instance = await client.instances.createFromTemplate({
  templateName: 'calculator-final',      // Name of the saved template
  newInstanceName: 'my-calculator-v2'   // Name for the new cloned instance
});

// The new instance inherits:
// - Description
// - Environment variables
// - Container template ID
// - Agent type (opencode, moltbot, etc.)
// - Region
// - VM size
// - Workspace files and state

// Use the cloned instance
await instance.run('Continue working on the project');
```

**Note:** `createFromTemplate()` clones from saved templates (instances you've saved). The cloned instance will preserve the agent type (e.g., if the template was a Moltbot instance, the clone will also be Moltbot). For creating custom Docker environments, use `templates.create()` instead.

### 3. Running Tasks

```javascript
// Simple task
const result = await instance.run('Create a hello.txt file');

// With options
const result = await instance.run('Build a web scraper', {
  model: 'anthropic/claude-sonnet-4.5',
  provider: 'openrouter',
  autoTools: true,
  timeout: 300000
});

// Access results
console.log(result.response);
console.log(result.tokensUsed);
console.log(result.duration_ms);
```

### 4. Instance Management

```javascript
// Check health
const health = await instance.health();

// Get file changes
const changes = await instance.getChanges();

// Stop instance
await instance.stop();

// Destroy instance
await instance.destroy();

// Refresh data
await instance.refresh();
```

### 5. Usage Tracking

```javascript
// Get token usage
const usage = await client.usage.getTokenUsage();
console.log(usage.monthlyTokens);
console.log(usage.monthlyCost);
console.log(usage.totalTokens);

// Get stats (legacy)
const stats = await client.usage.getStats();
```

## Examples

### Create and Use Instance

```javascript
const instance = await client.instances.create({
  name: 'web-builder'
});

await instance.run('Create a REST API with user CRUD');
await instance.run('Add JWT authentication');
await instance.run('Write tests');

const changes = await instance.getChanges();
console.log('Files modified:', changes);

await instance.destroy();
```

### Custom Environment

```javascript
const template = await client.templates.create({
  name: 'cuda-env',
  image: 'nvidia/cuda:12.2-runtime',
  registryType: 'dockerhub'
});

await template.waitUntilReady();

const instance = await client.instances.create({
  name: 'ml-trainer',
  templateId: template.templateId
});

await instance.run('Train a model on data.csv');
```

### Reuse Existing Instance

```javascript
// Create instance
const instance = await client.instances.create({
  name: 'persistent-agent'
});

// Do work
await instance.run('Install dependencies and setup project');

// Later, get the same instance
const sameInstance = await client.instances.getByName('persistent-agent');
await sameInstance.run('Continue working on the project');
```

### Clone from Saved Template

```javascript
// Create a new instance by cloning a saved template
const instance = await client.instances.createFromTemplate({
  templateName: 'web-app-template',
  newInstanceName: 'my-web-app-' + Date.now()
});

// The cloned instance has the same configuration and workspace
await instance.run('Add new features to the existing project');
await instance.destroy();
```

## Testing

```bash
# Run all tests
npm test

# Run E2E test
npm run test:e2e

# Run endpoint smoke test
npm run test:endpoints

# Run examples
npm run example
npm run example:abg
npm run example:reuse
npm run example:template
```

## API Reference

See [docs.md](./docs.md) for complete API documentation.

## Migration from v1.x

See [MIGRATION.md](./MIGRATION.md) for migration guide from version 1.x.

## Environment Variables

- `IN10NT_API_KEY` - Your API key (required)
- `IN10NT_API_URL` - API base URL (optional, defaults to production)

## License

MIT