Runtimes

A runtime is the running environment inside a space. Browser runtimes are the stable runtime type today.

Runtime = control
Run = observability

Use runtime APIs to launch, connect, invoke, move files, and stop. Use the current run to inspect what happened.

Create a browser runtime

1
const runtime = await space.runtimes.browser.launch({
2
  name: "quickbooks",
3
  profile: "quickbooks-bot",
4
  metadata: {
5
    customerJobId: "job_123",
6
  },
7
});

The runtime name is first-class. Use names like crm, quickbooks, or research so scripts and agents can reason about the environment.

Runtime metadata

1
console.log(runtime.id);
2
console.log(runtime.status);
3
console.log(runtime.activeRunId);

activeRunId is always present and nullable. Prefer runtime.currentRun() when you need the active run and its helpers.

1
const run = await runtime.currentRun();
2
3
await run.events.list();
4
await run.artifacts.list();

Control the runtime through a connection

1
const connection = await runtime.connections.create({
2
  protocol: "cdp",
3
});

Then pass connection.endpoint.url to your native browser framework.

1
import { chromium } from "playwright";
2
3
const browser = await chromium.connectOverCDP(connection.endpoint.url);

Stop a runtime

1
await runtime.stop();

Stopping a runtime tears down its active browser process and prevents new connection attaches.

Runtime types

Only browser CDP connections are requestable today.

Related

• Connections
• Browser Runtimes
• Runs