TypeScript SDK

The official @remotehost/sdk package is the server-side TypeScript interface to RemoteHost. It is generated from the same OpenAPI contract as the REST API, with a resource-oriented layer for commands, files, previews, metrics, and sandbox lifecycle operations.

Install

npm install @remotehost/sdk

Requires Node.js 20 or newer. Bun, Deno, edge runtimes, and custom fetch implementations are supported when they provide the standard Fetch and Web API globals.

Authenticate

Create a key and store it in your server environment. Never expose the key to browser code.

remote keys create --name production-backend
export REMOTEHOST_API_KEY=rh_...

import RemoteHost from "@remotehost/sdk";

const remotehost = new RemoteHost({
  orgId: "org_123",
});

The client reads REMOTEHOST_API_KEY by default. Pass apiKey explicitly when secrets are provided by your runtime rather than environment variables.

Create a sandbox

const sandbox = await remotehost.sandboxes.create({
  projectId: "project_123",
  agent: "codex",
  profile: "agent-standard",
});

Creation waits until the sandbox is running and the agent inside it answers a request, so the next operation can run immediately. Use waitForReady: false when you want the provisioning response without polling.

const sandbox = await remotehost.sandboxes.create({
  projectId: "project_123",
  agent: "codex",
  waitForReady: false,
});

await sandbox.waitUntilReady({ timeoutMs: 5 * 60_000 });

Retrieve an existing sandbox when only its id is available:

const sandbox = await remotehost.sandboxes.retrieve("sandbox_123");

Run commands

const result = await sandbox.commands.run("pnpm test", {
  timeoutSeconds: 300,
});

if (result.exitCode !== 0) {
  console.error(result.stderr);
}

Commands are non-interactive and run to completion. stdout and stderr are individually bounded at 64 KiB; truncated tells you when either limit was reached. Use the CLI or terminal WebSocket for interactive PTY sessions.

Work with files

const directory = await sandbox.files.list("/code/src");
const source = await sandbox.files.readText("/code/src/index.ts");

await sandbox.files.write("/code/src/config.json", JSON.stringify({ enabled: true }));
await sandbox.files.write("/code/assets/logo.png", imageBytes);

Relative paths resolve beneath /code. Binary files are transferred as base64 internally and returned as Uint8Array by readBytes. Individual reads and writes are limited to 2 MiB.

Create previews

Team previews require a signed-in RemoteHost member. Public previews are revocable URLs for the users of your own product.

const preview = await sandbox.previews.create({
  port: 3000,
  audience: "public",
  expiresInSeconds: 3600,
  endUserId: "usr_8f21",
});

console.log(preview.url);

const links = await sandbox.previews.list();
await sandbox.previews.revoke(links[0].id);

Lifecycle and resources

await sandbox.sleep();
await sandbox.wake();
await sandbox.waitUntilReady();

const metrics = await sandbox.metrics.get();
const recommendation = await sandbox.metrics.sample();

await sandbox.resize({ vcpu: 8, memoryGb: 16 });
await sandbox.destroy();

sleep preserves a persistent sandbox's disk while releasing its machine. destroy permanently removes it. The older stop and resume spellings remain available but are deprecated.

Errors, retries, and cancellation

import { RemoteHostAPIError } from "@remotehost/sdk";

try {
  await sandbox.commands.run("pnpm test");
} catch (error) {
  if (error instanceof RemoteHostAPIError) {
    console.error(error.status, error.code, error.requestId, error.message);
  }
  throw error;
}

code is set when the API has a machine-readable reason: rate_limited and limit_reached for plan limits, plan_required for a profile the plan does not include, and snapshot_in_progress for a wake that must be retried in a few seconds.

The SDK retries transient GET and HEAD failures twice with exponential backoff and honors Retry-After. Mutating requests are never replayed automatically. Configure this globally with maxRetries, or cancel an individual operation with signal or timeoutMs.

const remotehost = new RemoteHost({
  orgId: "org_123",
  maxRetries: 3,
  timeoutMs: 10 * 60_000,
});

await sandbox.files.read("large.log", { timeoutMs: 30_000 });

See the API Reference for the underlying REST operations and the Platform Guide for multi-tenant product architecture.