chaser-sdk

Official TypeScript SDK for Chaser.

This SDK targets the following surfaces:

• sessions
• workspaces
• exec
• command lifecycle
• files
• runtime self-tests and preview URLs
• browser CDP helpers
• accounts and organizations
• service accounts and keys
• billing
• lifecycle webhooks
• audit
• jobs

Installation

npm install chaser-sdk

Quickstart

import { ChaserClient } from 'chaser-sdk';

const client = new ChaserClient({
  apiKey: process.env.CHASER_API_KEY,
  account: 'personal'
});

const workspace = await client.workspaces.create({
  name: 'frontend-app',
  session_type: 'sandbox',
  image: 'ghcr.io/example/dev:latest'
});

const session = await client.sessions.create({
  workspace: workspace.name,
  session_type: 'sandbox'
});

await client.sessions.waitUntilReady(session.id);

const result = await client.exec.inSession(session.id, {
  command: 'node -v && pwd',
  cwd: '/workspace'
});

console.log(result.output);

Stateless exec

const result = await client.exec.run({
  ephemeral: true,
  image: 'node:20-bookworm',
  command: 'npm test',
  cwd: '/workspace'
});

File upload/download

await client.files.uploadText(session.id, '/workspace/hello.txt', 'hello from sdk');
const text = await client.files.downloadText(session.id, '/workspace/hello.txt');

Runtime diagnostics and previews

const diagnostics = await client.sessions.selfTest(session.id);
const previewUrl = client.sessions.forwardUrl(session.id, 3000);
console.log(diagnostics.runtime.tools.node, previewUrl);

Network controls

const session = await client.sessions.create({
  ephemeral: true,
  session_type: 'sandbox',
  proxy: 'socks5h://user:[email protected]:1080'
});

Use the root-level proxy field for the public API contract. The SDK still accepts the older network.proxy.url shape and normalizes it for backward compatibility, but new code should send proxy directly.

Browser CDP helper

const browser = await client.sessions.create({
  session_type: 'browser',
  ephemeral: true
});

const version = await client.browser.version(browser.id);
const cdpUrl = await client.browser.cdpWebSocketUrl(browser.id);
const cdp = await client.browser.connect(browser.id);
console.log(version.Browser, cdpUrl);

await cdp.send('Browser.getVersion');
cdp.close();

Workspace selectors and delete

const workspace = await client.workspaces.create({
  name: 'frontend-app',
  session_type: 'sandbox'
});

// Names are preferred when unambiguous; UUIDs work too.
await client.workspaces.delete(workspace.name, { force: true });

If a workspace name is ambiguous inside the active account, the API returns a workspace_name_ambiguous error and you should use the workspace UUID instead.

Account-scoped automation

const orgClient = client.withAccount('Acme Engineering');

const serviceAccount = await orgClient.accounts.serviceAccounts.create('ci-bot');
const key = await orgClient.accounts.serviceAccounts.keys.create(serviceAccount.id, {
  name: 'ci-key',
  scopes: ['sessions.read', 'workspaces.write', 'exec.write', 'files.read', 'webhooks.write']
});

console.log(key.key);

Command lifecycle

const started = await client.exec.inSession(session.id, {
  command: 'npm run dev',
  cwd: '/workspace',
  background: true
});

if (!started.command_id) {
  throw new Error('expected background command_id');
}

const command = await client.commands.waitForCompletion(session.id, started.command_id, {
  timeoutMs: 30_000
});

console.log(command.status, command.exit_code);

Notes

• apiKey and token both map to bearer authentication. Either can be used.
• account maps to the X-Chaser-Account header.
• File upload/download helpers target sandbox sessions only.
• client.browser.connect() uses the public CDP endpoint and waits for browser readiness by default.
• For authenticated upstream proxies, embed credentials in the proxy URL, for example socks5h://user:[email protected]:1080.

Error handling

import { ChaserApiError } from 'chaser-sdk';

try {
  await client.workspaces.delete('frontend-app');
} catch (error) {
  if (error instanceof ChaserApiError) {
    console.error(error.status, error.code, error.rateLimit?.remaining);
  }
  throw error;
}