TypeScript SDK

The Agent Computer TypeScript SDK exposes a computer-first client for lifecycle, execution, ports, shares, snapshots, and typed terminal workflows.

Install

Install the published package, then create an AgentComputer client with an API key or access token.

pnpm add aicomputer

Quickstart

Create a computer, wait for it to run, execute a command, and stop it when you are done.

import { AgentComputer } from "../src/index.js";

const client = new AgentComputer({
  apiKey: "<api-key>",
});

const computer = await client.computers.create({
  displayName: "Quickstart computer",
});

await computer.ensureRunning();

const result = await computer.commands.run(["node", "--version"]);
console.log(result.stdout.trim());

await computer.ensureStopped();

Size presets

Pass sizePreset or explicit memoryMiB and storageBytes when creating a computer.

const computer = await client.computers.create({
  handle: "my-large-computer",
  memoryMiB: 16 * 1024,
  storageBytes: 50 * 1024 * 1024 * 1024,
});

Preset	RAM	Storage
`ram-2g`	2 GiB	5 GiB
`ram-4g`	4 GiB	10 GiB
`ram-8g`	8 GiB	25 GiB

Run commands

Use computer.commands.run for one-shot execution or computer.commands.start when you need a typed streaming handle with wait(), disconnect(), and kill().

import { AgentComputer } from "../src/index.js";

const client = new AgentComputer({
  apiKey: "<api-key>",
});

const computer = await client.computers.create({
  displayName: "Command runner",
});

await computer.ensureRunning();

const result = await computer.commands.run([
  "python3",
  "-c",
  "print('hello from agentcomputer')",
]);

console.log(result.exitCode, result.stdout.trim());

Files

Read and write the computer's workspace through computer.files. Works on running and stopped computers; stopped calls don't start the VM or accrue runtime. Paths must stay under /home/node/workspace, and response entries are relative to that root.

import { AgentComputer } from "@microagentcomputer/agentcomputer";

const client = new AgentComputer({ apiKey: process.env.COMPUTER_API_KEY! });
const computer = await client.computers.resolve("my-box"); // id or handle

await computer.files.writeText(
  "/home/node/workspace/notes.txt",
  "hello from the sdk\n",
);

const notes = await computer.files.readText("/home/node/workspace/notes.txt");

const entries = await computer.files.list("/home/node/workspace");
for (const entry of entries) {
  console.log(entry.type, entry.path, entry.size_bytes);
}

await computer.files.patch("/home/node/workspace/notes.txt", [
  { find: "hello", replace: "hi" },
]);

const hits = await computer.files.grep("TODO", {
  path: "/home/node/workspace",
  maxMatches: 50,
});

const logo = await computer.files.readBytes("/home/node/workspace/logo.png");
await computer.files.writeBytes("/home/node/workspace/logo.copy.png", logo);

Publish ports

Start a long-lived process, wait for the port to become ready, and publish a stable public URL.

import { AgentComputer } from "../src/index.js";

const client = new AgentComputer({
  apiKey: "<api-key>",
});

const computer = await client.computers.create({
  displayName: "Published port example",
});

await computer.ensureRunning();

const server = await computer.commands.start(
  ["python3", "-m", "http.server", "3000"],
  {
    onStdout: (chunk) => console.log(chunk),
    onStderr: (chunk) => console.error(chunk),
  },
);

await computer.waitForPort(3000);

const published = await computer.ports.publish({
  port: 3000,
  name: "app",
});

console.log(published.public_url);

await server.kill();

PTY

Use the PTY client for interactive shells, REPLs, and terminal-style agent workflows.

import { AgentComputer } from "../src/index.js";

const client = new AgentComputer({
  apiKey: "<api-key>",
});

const computer = await client.computers.create({
  displayName: "PTY example",
});

await computer.ensureRunning();

const shell = await computer.pty.create({
  cols: 120,
  rows: 32,
  onData: (chunk) => console.log(chunk),
});

await shell.sendInput("uname -a\n");
await shell.resize(140, 40);
await shell.kill();

Reference

Generated from the SDK source. See the full type definitions in the package source.

Core clients

Create a client, create computers, and work with the high-level computer model.

AgentComputer

Top-level SDK client for the Agent Computer public API.

Property	Type
`images`	`ComputerImagesClient`
`computers`	`ComputersClient`
`snapshots`	`SnapshotsClient`
`sshKeys`	`SSHKeysClient`

Method	Signature
`me`	`(signal?: AbortSignal): Promise<{ ... }; credit_balance: number; featur...`
`usage`	`(signal?: AbortSignal): Promise<{ ... } }>`
`resolveShare`	`(shareToken: string, signal?: AbortSignal): Promise<{ ... } }>`
`redeemShare`	`(shareToken: string, body?: Partial<{ kind: "browser" \| "...): Promise<{ ... } } }>`
`waitForOperation`	`(operationOrId: string \| Pick<{ ... }, "id">, options: WaitOptions): Promise<{ ... }>`
`waitForComputerState`	`(computerId: string, targetState: "failed" \| "deleted" \| ...): Promise<Computer>`
`computer`	`(idOrHandle: string): Promise<Computer>`

AgentComputerOptions - Options for configuring API access, timeouts, and polling defaults.

ComputersClient

Create, list, and resolve computers.

Method	Signature
`list`	`(signal?: AbortSignal): Promise<Computer[]>`
`get`	`(computerId: string, signal?: AbortSignal): Promise<Computer>`
`getByHandle`	`(handle: string, signal?: AbortSignal): Promise<Computer \| null>`
`resolve`	`(idOrHandle: string, signal?: AbortSignal): Promise<Computer>`
`checkCapacity`	`(options: ComputerCapacityOptions, signal?: AbortSignal): Promise<{ ... }; size_preset: string }>`
`create`	`(options: ComputerCreateOptions, signal?: AbortSignal): Promise<Computer>`
`ensure`	`(options: ComputerEnsureOptions, signal?: AbortSignal): Promise<Computer>`

ComputerImagesClient

List and inspect platform computer images.

Method	Signature
`list`	`(signal?: AbortSignal): Promise<{ ... }[]>`
`get`	`(imageId: string, signal?: AbortSignal): Promise<{ ... }>`
`getDefault`	`(signal?: AbortSignal): Promise<{ ... }>`
`getDefaultForPlatform`	`(platform: ComputerPlatform, signal?: AbortSignal): Promise<{ ... }>`

Computer

High-level computer model with lifecycle, execution, readiness, and collaboration helpers.

Property	Type
`commands`	`ComputerCommandsClient`
`pty`	`ComputerPtyClient`
`files`	`ComputerFilesClient`
`git`	`ComputerGitClient`
`mounts`	`ComputerMountsClient`
`ports`	`ComputerPortsClient`
`shares`	`ComputerSharesClient`
`snapshots`	`ComputerSnapshotsClient`
`raw`	`raw`
`id`	`id`
`handle`	`handle`
`displayName`	`displayName`
`state`	`state`
`sourceKind`	`sourceKind`
`sourceSnapshotId`	`sourceSnapshotId`
`createdAt`	`createdAt`
`updatedAt`	`updatedAt`
`deletedAt`	`deletedAt`
`primaryUrl`	`primaryUrl`
`failureReason`	`failureReason`

Method	Signature
`refresh`	`(signal?: AbortSignal): Promise<Computer>`
`update`	`(options: ComputerUpdateOptions, signal?: AbortSignal): Promise<Computer>`
`start`	`(signal?: AbortSignal): Promise<Computer>`
`stop`	`(signal?: AbortSignal): Promise<Computer>`
`resize`	`(options: ComputerResizeOptions \| LowLevelComputerResizeOptions, signal?: AbortSignal): Promise<Computer>`
`delete`	`(signal?: AbortSignal): Promise<void>`
`transfer`	`(options: TransferComputerOptions): Promise<Computer>`
`usage`	`(signal?: AbortSignal): Promise<ComputerUsageEnvelope>`
`ensureReady`	`(options: WaitOptions): Promise<Computer>`
`ensureRunning`	`(options: WaitOptions): Promise<Computer>`
`ensureStopped`	`(options: WaitOptions): Promise<Computer>`
`waitUntilRunning`	`(options: WaitOptions): Promise<Computer>`
`waitUntilStopped`	`(options: WaitOptions): Promise<Computer>`
`getConnection`	`(signal?: AbortSignal): Promise<{ ... }; ports: { ... }[] }>`
`createBrowserAccess`	`(options: ExecSessionCreateOptions): Promise<{ ... } }>`
`createVNCAccess`	`(options: ExecSessionCreateOptions): Promise<{ ... } }>`
`createSSHCertificate`	`(body: { ssh_key_id: string; ttl_seconds: number }, signal?: AbortSignal): Promise<{ ... }>`
`execCapabilities`	`(signal?: AbortSignal): Promise<readonly string[]>`
`supportsCapability`	`(capability: ComputerCapability, signal?: AbortSignal): Promise<boolean>`
`requireCapability`	`(capability: "files" \| "git", signal?: AbortSignal): Promise<readonly string[]>`
`waitForPort`	`(port: number, options: WaitOptions): Promise<{ ... }>`
`waitForUrl`	`(url: string, options: WaitOptions): Promise<Response>`
`waitForProcess`	`(selectorOrPredicate: CommandSelector \| (command: CommandInfo) => boolean, options: WaitOptions): Promise<CommandInfo>`
`waitForFile`	`(path: string, options: WaitOptions): Promise<void>`

ComputerCreateOptions - Options for creating a computer from the default or explicit source.

ComputerEnsureOptions - Create options that also support resolving an existing computer by handle.

ComputerUpdateOptions - Mutable computer properties exposed by the SDK.

ComputerCapability - Capability names advertised by exec sessions and used by typed module guards.

ComputerState

ComputerSource

WaitOptions - Polling and timeout controls used by readiness and lifecycle helpers.

Commands

Run one-shot commands or manage long-lived processes with typed handles.

ComputerCommandsClient

Typed process APIs for run, start, connect, list, stdin, close, and kill.

Method	Signature
`run`	`(command: string \| readonly string[], options: CommandRunOptions): Promise<CommandResult>`
`start`	`(command: string \| readonly string[], options: CommandStartOptions): Promise<CommandHandle>`
`connect`	`(selector: CommandSelector, options: Omit<CommandStartOptions, "stdin">): Promise<CommandHandle>`
`list`	`(signal?: AbortSignal): Promise<CommandInfo[]>`
`sendStdin`	`(selector: CommandSelector, data: string \| Uint8Array<ArrayBufferLike>, signal?: AbortSignal): Promise<void>`
`sendPtyInput`	`(selector: CommandSelector, data: string \| Uint8Array<ArrayBufferLike>, signal?: AbortSignal): Promise<void>`
`closeStdin`	`(selector: CommandSelector, signal?: AbortSignal): Promise<void>`
`kill`	`(selector: CommandSelector, signalName: CommandSignal, signal?: AbortSignal): Promise<void>`
`resizePty`	`(selector: CommandSelector, cols: number, rows: number, signal?: AbortSignal): Promise<void>`

CommandRunOptions - Options for one-shot command execution.

CommandStartOptions - Options for long-lived commands, including streaming hooks and tagging.

CommandSelector - Select a process by pid or tag when reconnecting or sending control signals.

CommandSignal - Supported signal names for terminating commands.

CommandInfo - Metadata returned when listing running commands.

CommandResult - Buffered command output and exit details.

CommandHandle

Streaming handle for a long-lived command with wait, disconnect, kill, and stdin helpers.

Property	Type
`pid`	`pid`
`stdout`	`stdout`
`stderr`	`stderr`

Method	Signature
`wait`	`(options: { rejectOnNonZero: boolean }): Promise<CommandResult>`
`disconnect`	`(): Promise<void>`
`kill`	`(signal: CommandSignal, requestSignal?: AbortSignal): Promise<void>`
`sendStdin`	`(data: string \| Uint8Array<ArrayBufferLike>, requestSignal?: AbortSignal): Promise<void>`
`closeStdin`	`(requestSignal?: AbortSignal): Promise<void>`
`awaitPid`	`(): Promise<number>`

PTY

Attach interactive terminals with typed input, resize, and output streaming.

ComputerPtyClient

Interactive terminal APIs for starting or reconnecting PTY sessions.

Method	Signature
`create`	`(options: PtyStartOptions): Promise<PtySession>`
`start`	`(command: string \| readonly string[], options: PtyStartOptions): Promise<PtySession>`
`attach`	`(selector: CommandSelector, options: Pick<PtyStartOptions...): Promise<PtySession>`
`connect`	`(selector: CommandSelector, options: Pick<PtyStartOptions...): Promise<PtySession>`

PtyStartOptions - Options for PTY startup, including size and output callbacks.

PtyResult - Buffered PTY output and exit details.

PtySession

Streaming PTY session with input, resize, wait, disconnect, and kill helpers.

Property	Type
`pid`	`pid`
`output`	`output`

Method	Signature
`wait`	`(options: { rejectOnNonZero: boolean }): Promise<PtyResult>`
`sendInput`	`(data: string \| Uint8Array<ArrayBufferLike>, requestSignal?: AbortSignal): Promise<void>`
`resize`	`(cols: number, rows: number, requestSignal?: AbortSignal): Promise<void>`
`kill`	`(signal: CommandSignal, requestSignal?: AbortSignal): Promise<void>`
`disconnect`	`(): Promise<void>`
`awaitPid`	`(): Promise<number>`

Computer modules

Use published ports, shares, snapshots, SSH keys, and runtime-less filesystem access from a Computer.

ComputerPortsClient

Publish, list, and remove app ports for a computer.

Method	Signature
`list`	`(signal?: AbortSignal): Promise<{ ... }[]>`
`publish`	`(options: PublishPortOptions): Promise<{ ... }>`
`delete`	`(port: number, signal?: AbortSignal): Promise<{ ... }>`

PublishPortOptions - Options for publishing a stable port name and visibility.

ComputerSharesClient

Create and manage public computer share links.

Method	Signature
`list`	`(signal?: AbortSignal): Promise<{ ... }[]>`
`createLink`	`(options: ShareLinkOptions): Promise<{ ... }>`
`delete`	`(shareId: string, signal?: AbortSignal): Promise<void>`

ShareLinkOptions - Options for direct share links.

TransferComputerOptions - Options for transferring a computer to another workspace (Clerk organization).

ComputerSnapshotsClient

List and create snapshots for a computer.

Method	Signature
`list`	`(signal?: AbortSignal): Promise<{ ... }[]>`
`create`	`(signal?: AbortSignal): Promise<{ ... }>`

SnapshotsClient

Fetch, delete, and restore snapshots by id.

Method	Signature
`get`	`(snapshotId: string, signal?: AbortSignal): Promise<{ ... }>`
`delete`	`(snapshotId: string, signal?: AbortSignal): Promise<{ ... }>`
`restore`	`(snapshotId: string, options: SnapshotRestoreOptions): Promise<Computer>`

SnapshotRestoreOptions - Options for restoring a snapshot into a new computer.

SSHKeysClient

List and create SSH keys through the public API.

Method	Signature
`list`	`(signal?: AbortSignal): Promise<{ ... }[]>`
`create`	`(body: { name: string; public_key: string }, signal?: AbortSignal): Promise<{ ... }>`
`delete`	`(sshKeyId: string, signal?: AbortSignal): Promise<void>`

ComputerFilesClient

Runtime-less filesystem client for reading and writing a computer workspace without starting runtime.

Method	Signature
`readText`	`(path: string, opts?: AbortSignal \| FileReadOptions): Promise<string>`
`readBytes`	`(path: string, opts?: FileReadOptions): Promise<Uint8Array<ArrayBufferLike>>`
`writeText`	`(path: string, content: string, opts?: AbortSignal \| FileWriteOptions): Promise<void>`
`writeBytes`	`(path: string, content: Uint8Array, opts?: FileWriteOptions): Promise<void>`
`remove`	`(path: string, opts?: AbortSignal \| FileRemoveOptions): Promise<void>`
`list`	`(path: string, opts: FileListOptions): Promise<ComputerFileEntry[]>`
`stat`	`(path: string, opts: FileReadOptions): Promise<ComputerFileStat>`
`exists`	`(path: string, opts: FileReadOptions): Promise<boolean>`
`patch`	`(path: string, edits: FilePatchRequest, opts: FilePatchOptions): Promise<{ version: number }>`
`readRange`	`(path: string, range: FileReadRange, opts: FileReadOptions): Promise<Uint8Array<ArrayBufferLike>>`
`writeRange`	`(path: string, range: FileWriteRange, content: Uint8Array, opts: FileWriteOptions): Promise<void>`
`mkdir`	`(path: string, opts: FileMkdirOptions): Promise<void>`
`move`	`(from: string, to: string, opts: FileReadOptions): Promise<void>`
`grep`	`(pattern: string, opts: FileGrepOptions): Promise<ComputerFileGrepMatch[]>`

ComputerGitClient

Reserved git module that fails explicitly until the backend advertises git support.

Method	Signature
`status`	`(signal?: AbortSignal): Promise<string>`
`clone`	`(repoUrl: string, signal?: AbortSignal): Promise<void>`
`pull`	`(signal?: AbortSignal): Promise<void>`