Skip to main content

​
Installation

The SDK is written in TypeScript and ships .d.ts + source maps out of the box: 
npm install @in10nt/sdk
All types are exported from the main entry point: 
import {
  Instance,
  In10ntClient,
  type CreateInstanceConfig,
  type RunOptions,
  type RunResult,
  type TokenUsage,
} from '@in10nt/sdk';

​
Type Definitions

​
Client Configuration

interface ClientConfig {
  apiKey?: string;
  baseURL?: string;
  logger?: Logger;
}

interface Logger {
  debug(message: string, ...args: unknown[]): void;
  info(message: string, ...args: unknown[]): void;
  warn(message: string, ...args: unknown[]): void;
  error(message: string, ...args: unknown[]): void;
}

​
Container Templates

interface CreateContainerTemplateConfig {
  name: string;
  image: string;
  registryType: 'dockerhub' | 'private' | 'gcr';
  description?: string;
  registryAuth?: Record<string, unknown>;
}

interface ContainerTemplateData {
  templateId: string;
  name: string;
  status: string;
  image?: string;
  registryType?: string;
  description?: string;
  error?: string;
}

​
Instances

interface CreateInstanceConfig {
  name: string;
  description: string;
  containerTemplateId?: string;
  vmImage?: string;
  vmSize?: string;
  region?: string;
  env?: Record<string, string>;
}

interface InstanceData {
  instanceId: string;
  name: string;
  description: string;
  status: string;
  region: string;
  vmSize: string;
  createdAt: string;
  agentUrl: string;
  env?: Record<string, string>;
}

​
Task Execution

interface RunOptions {
  model?: string;
  provider?: string;
  system?: string;
  tools?: unknown[];
  maxTokens?: number;
  timeout?: number;
  pollInterval?: number;
  maxPollTime?: number;
  healthCheckRetries?: number;
  healthCheckDelay?: number;
  waitForHealth?: boolean;
  background?: boolean;
  autoTools?: boolean;
}

interface RunResult {
  response: string;
  usage?: Record<string, unknown>;
  tokensUsed: number;
  duration_ms?: number;
  messageId?: string;
  toolsUsed?: unknown[];
  completedAt?: string;
  taskId?: string;
  status?: string;
}

interface PollOptions {
  pollInterval?: number;
  maxPollTime?: number;
}

​
Usage & Billing

interface TokenUsage {
  monthlyTokens: number;
  totalTokens: number;
  monthlyCost: number;
  totalCost: number;
  lastUsage: string;
}

​
Errors

class In10ntError extends Error {
  statusCode?: number;
  response?: unknown;
}

class TimeoutError extends In10ntError {}
class HealthCheckError extends In10ntError {}
class TaskPollError extends In10ntError {}
class TemplateNotFoundError extends In10ntError {}

​
Class Definitions

​
Instance

class Instance {
  // Properties
  readonly instanceId: string;
  name: string;
  description: string;
  status: string;
  region: string;
  vmSize: string;
  createdAt: string;
  agentUrl: string;
  env?: Record<string, string>;

  // Namespaces
  readonly tasks: TasksNamespace;
  readonly ports: PortsNamespace;
  readonly files: FilesNamespace;
  readonly tools: ToolsNamespace;
  readonly integrations: IntegrationsNamespace;

  // Static factory methods
  static create(config: CreateInstanceConfig, clientConfig?: ClientConfig): Promise<Instance>;
  static connect(instanceId: string, clientConfig?: ClientConfig): Promise<Instance>;
  static list(clientConfig?: ClientConfig): Promise<Instance[]>;

  // Instance methods
  run(prompt: string, options?: RunOptions): Promise<RunResult>;
  execute(command: string): Promise<unknown>;
  stop(): Promise<unknown>;
  restart(): Promise<unknown>;
  destroy(): Promise<void>;
  health(): Promise<HealthResult>;
  snapshot(): Promise<SnapshotResult>;
  getProxyUrl(port: number): string;
  refresh(): Promise<this>;
  streamLogs(onLog: (event: unknown) => void): Promise<() => void>;
}

​
In10ntClient

class In10ntClient {
  readonly instances: InstanceManager;
  readonly templates: ContainerTemplateManager;
  readonly savedTemplates: SavedTemplateManager;
  readonly usage: UsageManager;

  constructor(config?: ClientConfig);
}

​
ContainerTemplate

class ContainerTemplate {
  readonly templateId: string;
  readonly name: string;
  status: string;
  readonly image?: string;
  readonly registryType?: string;
  readonly description?: string;
  readonly error?: string;

  waitUntilReady(options?: WaitUntilReadyOptions): Promise<this>;
  delete(): Promise<void>;
}

​
Namespace Classes

class TasksNamespace {
  list(): Promise<TaskData[]>;
  getStatus(taskId: string): Promise<TaskData>;
  poll(taskId: string, options?: PollOptions): Promise<RunResult>;
}

class PortsNamespace {
  list(): Promise<PortInfo[]>;
  open(ports: number[]): Promise<unknown>;
  getProxyUrl(port: number): string;
}

class FilesNamespace {
  getChanges(): Promise<FileChanges>;
  tree(): Promise<unknown>;
}

class ToolsNamespace {
  list(): Promise<ToolInfo[]>;
  getMcpConfig(): Promise<McpConfig>;
}

class IntegrationsNamespace {
  get(): Promise<IntegrationConfig>;
  set(config: IntegrationConfig): Promise<unknown>;
}

​
Usage Example

import { Instance, In10ntClient, createConsoleLogger } from '@in10nt/sdk';
import type {
  CreateInstanceConfig,
  RunOptions,
  RunResult,
  TokenUsage
} from '@in10nt/sdk';

// Zero-config path
async function buildAPI(): Promise<void> {
  const config: CreateInstanceConfig = {
    name: 'api-builder',
    description: 'REST API builder',
    env: {
      NODE_ENV: 'development'
    }
  };

  const instance = await Instance.create(config);

  const options: RunOptions = {
    model: 'anthropic/claude-sonnet-4.5',
    timeout: 300_000,
    waitForHealth: true
  };

  const result: RunResult = await instance.run(
    'Build a REST API with user CRUD',
    options
  );

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

  await instance.destroy();
}

// Client path
async function withClient(): Promise<void> {
  const client = new In10ntClient({
    logger: createConsoleLogger()
  });

  const instance = await client.instances.create({
    name: 'typed-agent',
    description: 'Typed example'
  });

  // Namespaced methods are fully typed
  const tasks = await instance.tasks.list();
  const ports = await instance.ports.list();
  const changes = await instance.files.getChanges();

  // Usage tracking
  const usage: TokenUsage = await client.usage.getTokenUsage();
  console.log(`Monthly cost: $${usage.monthlyCost}`);

  await instance.destroy();
}

buildAPI().catch(console.error);

​
Custom Type Extensions

Extend types for your use case: 
import { Instance, In10ntClient } from '@in10nt/sdk';
import type { RunResult } from '@in10nt/sdk';

// Custom session type
interface AgentSession {
  id: string;
  instance: Instance;
  createdAt: Date;
  tasks: Task[];
}

interface Task {
  prompt: string;
  result: string;
  tokensUsed: number;
  timestamp: Date;
}

class SessionManager {
  private client: In10ntClient;
  private sessions: Map<string, AgentSession>;

  constructor(client: In10ntClient) {
    this.client = client;
    this.sessions = new Map();
  }

  async createSession(name: string): Promise<AgentSession> {
    const instance = await this.client.instances.create({
      name,
      description: `Session: ${name}`
    });

    const session: AgentSession = {
      id: instance.instanceId,
      instance,
      createdAt: new Date(),
      tasks: []
    };

    this.sessions.set(session.id, session);
    return session;
  }

  async runTask(sessionId: string, prompt: string): Promise<Task> {
    const session = this.sessions.get(sessionId);
    if (!session) throw new Error('Session not found');

    const result: RunResult = await session.instance.run(prompt);

    const task: Task = {
      prompt,
      result: result.response,
      tokensUsed: result.tokensUsed,
      timestamp: new Date()
    };

    session.tasks.push(task);
    return task;
  }

  async closeSession(sessionId: string): Promise<void> {
    const session = this.sessions.get(sessionId);
    if (session) {
      await session.instance.destroy();
      this.sessions.delete(sessionId);
    }
  }
}

​
Type Guards

Create type guards for runtime checking: 
import type { RunResult } from '@in10nt/sdk';
import { Instance } from '@in10nt/sdk';

function isRunResult(obj: unknown): obj is RunResult {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    typeof (obj as RunResult).response === 'string' &&
    typeof (obj as RunResult).tokensUsed === 'number'
  );
}

function isInstance(obj: unknown): obj is Instance {
  return (
    typeof obj === 'object' &&
    obj !== null &&
    typeof (obj as Instance).instanceId === 'string' &&
    typeof (obj as Instance).status === 'string'
  );
}

// Usage
const result = await instance.run('Task');
if (isRunResult(result)) {
  console.log(`Valid result: ${result.tokensUsed} tokens`);
}

​
Generic Wrapper

Create a generic wrapper for type-safe environment variables: 
import { Instance, In10ntClient } from '@in10nt/sdk';
import type { ClientConfig } from '@in10nt/sdk';

class TypedClient<TEnv extends Record<string, string> = Record<string, string>> {
  private client: In10ntClient;

  constructor(config?: ClientConfig) {
    this.client = new In10ntClient(config);
  }

  async createInstance(
    name: string,
    description: string,
    env: TEnv
  ): Promise<Instance> {
    return this.client.instances.create({ name, description, env });
  }
}

// Usage with typed env
interface MyEnv {
  API_KEY: string;
  DATABASE_URL: string;
  NODE_ENV: 'development' | 'production';
}

const typedClient = new TypedClient<MyEnv>();

const instance = await typedClient.createInstance(
  'my-app',
  'My application',
  {
    API_KEY: 'key',
    DATABASE_URL: 'postgres://...',
    NODE_ENV: 'development'
  }
);