TypeScript additions

The hand-written helpers of @trycua/cua: embedded, connect, Image, probes, sidecars, specs and MCP.

Import from @trycua/cua. This page covers the hand-written TypeScript layer; the generated native binding (sandboxes, guest, fleet, spaces objects) is documented per object in the Cua SDK reference.

npm install @trycua/cua (0.2.0) installs the Node package; native code ships as per-platform optional packages (@trycua/cua-darwin-arm64, @trycua/cua-linux-x64-gnu, ...).

Entry point	Use it for
`@trycua/cua`	`embedded()`, `connect()`, every generated object, and the helpers on this page
`@trycua/cua/spaces`, `/spaces/transport`, `/spaces/host`	Spaces threads, approvals and transports
`@trycua/cua/browser`	A WebAssembly subset: cua-spacesd over gRPC-Web and a Fleet client with a static bearer. No sandboxes, local runtimes, Spaces, daemon, file transfer or media. Give it a short-lived token from your backend, never client secrets

cua does not implement MCP: connectMcp(await sb.mcpConfig(service, undefined)) hands the endpoint to the official SDK (npm install @modelcontextprotocol/client). Cloud bearers are short-lived, so fetch a config per connection.

Interfaces#

ImageOptions#

Options for Image.linux() / windows() / macos().

Properties#

Property	Type
`tier?`	`ImageTier`
`version?`	`string`

McpEndpointConfig#

Where an MCP endpoint is: Sandbox.mcpConfig() returns one.

Properties#

Property	Type
`headers`	`object`[] \| `Record`<`string`, `string`>
`url`	`string`

Type Aliases#

ImageTier#

type ImageTier = "slim" | "full" | "xcode" | `xcode-${string}`;

An image tier: slim, full (the default), or on macOS xcode / xcode-<X.Y>.

Variables#

Image#

const Image: object;

Canonical images: Image.linux() is ghcr.io/trycua/linux:24.04 (CUA_IMAGE_LINUX overrides it), Image.windows() ghcr.io/trycua/windows:2022, Image.macos() ghcr.io/trycua/macos:26. These are the full tier (dev tooling); { tier: "slim" } is the minimal image CI runs and, on macOS, { tier: "xcode" } adds a pinned Xcode. Image.omarchy() is ghcr.io/trycua/omarchy:edge, an amd64 VM. Images CI has not published yet throw ImageNotPublished; pass the reference to fromRegistry to use one anyway. Image.resolve(ref, backend) is the one resolver: the digest-pinned variant a backend runs (rootfs, the -disk containerDisk, Lume).

Type Declaration#

Name	Type	Description
`fromRegistry()`	(`reference`) => `string`	-
`linux()`	(`version?`, `tier?`) => `string`	-
`macos()`	(`version?`, `tier?`) => `string`	-
`omarchy()`	(`channel?`) => `string`	Omarchy (Arch Linux, Hyprland) with cua-spacesd: an amd64 VM.
`resolve()`	(`reference`, `backend`, `arch?`) => `ResolvedImage`	-
`windows()`	(`version?`, `tier?`) => `string`	-

Pool#

const Pool: object;

Pool.apply(fleet, name, spec, options): the one pool writer, the same call as fleet.apply. Named pools are compared against a spec with fleet.checkPoolSpec (raises CuaError.PoolSpecMismatch with a diff) and updated with fleet.applyPoolTemplate; fleet.exportPool(name).terraform prints the equivalent fleets_pool block.

Type Declaration#

Name	Type
`apply()`	(`fleet`, `name`, `spec`, `options`) => `Promise`<`FleetPool`>

registrySecret#

const registrySecret: object;

Credentials for a private registry image (registrySecret on SandboxCreateOptions). Locally they authenticate the pull; in the cloud the SDK stores them as the sandbox's registry pull secret. Never logged.

Type Declaration#

Name	Type	Description
`awsEcr()`	(`region?`) => `RegistrySecret`	A private Amazon ECR image: a login token from the AWS CLI.
`basic()`	(`username`, `password`, `registry?`) => `RegistrySecret`	A user name and password (or token).
`fromEnv()`	(`usernameVar`, `passwordVar`, `registry?`) => `RegistrySecret`	Read from environment variables at create time.

Functions#

ambiguousCandidates()#

function ambiguousCandidates(error): string[];

The qualified refs (local:box, cloud:box) a CuaError.AmbiguousSandbox lists: a bare sandbox name that matches sandboxes in more than one location. Empty for any other error.

Parameters#

Parameter	Type
`error`	`unknown`

Returns#

string[]

connect()#

function connect(address?, token?): CuaLike;

A client of a running cua daemon (socket path or loopback URL).

Parameters#

Parameter	Type
`address?`	`string`
`token?`	`string`

Returns#

CuaLike

connectMcp()#

function connectMcp(config, clientInfo?): Promise<any>;

Connects the official SDK's Client to config over streamable HTTP. Fleet bearers are short-lived: fetch a fresh config per connection.

Parameters#

Parameter	Type
`config`	`McpEndpointConfig`
`clientInfo`	{ `name`: `string`; `version`: `string`; }
`clientInfo.name`	`string`
`clientInfo.version`	`string`

Returns#

Promise<any>

cuaErrorDocUrl()#

function cuaErrorDocUrl(error): string | undefined;

The link to a CuaError's entry (cause and fix) on the errors reference; undefined for any other value. Every CuaError also carries it as docUrl.

Parameters#

Parameter	Type
`error`	`unknown`

Returns#

string | undefined

embedded()#

function embedded(config?): CuaLike;

An SDK runtime in this process (no I/O until the first call). Fleet uses CUA_CLIENT_ID/CUA_CLIENT_SECRET (or FLEETS_TOKEN); pass fleetFromSession: true to fall back to the cua auth login session.

Parameters#

Parameter	Type
`config`	`Partial`<`CuaConfig`>

Returns#

CuaLike

http()#

function http(service, path?): ReadinessProbe;

Ready once GET path on the declared service returns 2xx.

Parameters#

Parameter	Type	Default value
`service`	`string`	`undefined`
`path`	`string`	`"/"`

Returns#

ReadinessProbe

mcpHeaders()#

function mcpHeaders(config): Record<string, string>;

The headers as a plain object.

Parameters#

Parameter	Type
`config`	`McpEndpointConfig`

Returns#

Record<string, string>

poolOptions()#

function poolOptions(opts?): PoolOptions;

How a pool keeps capacity for a SandboxSpec (warm floor, size, TTLs, runtime).

Parameters#

Parameter	Type
`opts`	`Partial`<`PoolOptions`>

Returns#

PoolOptions

sandboxSpec()#

function sandboxSpec(image, opts?): SandboxSpec;

What a sandbox runs: the one model behind Sandbox.create, managed pools and fleet.apply(name, spec, options). env and services take plain objects too. Unset fields keep Fleet's defaults (and are not compared by fleet.checkPoolSpec).

const spec = sandboxSpec("python:3.12-slim", {
  command: ["python", "-m", "srv"], services: { mcp: 8765 }, readiness: http("mcp", "/health") })
await c.fleet().apply("my-pool", spec, poolOptions({ warm: true, idleTtlSeconds: 3600 }))

Parameters#

Parameter	Type
`image`	`string`
`opts`	`Partial`<`Omit`<`SandboxSpec`, `"image"` \| `"env"` \| `"services"`>> & `object`

Returns#

SandboxSpec

sidecar()#

function sidecar(image, opts?): Container;

A sidecar container, addressed by name on every runtime: the sandbox reaches it at its name (and on localhost where they share a network namespace), it reaches the sandbox at main, and services may name its ports. Local containers (with runtime: "runc") and every cloud sandbox; local VM sandboxes refuse sidecars. With sidecars the service names main, sidecars and sc are reserved.

SandboxCreateOptions.create({ image: "python:3.12-slim",
  sidecars: [sidecar("redis:7-alpine", { ports: [6379] })],
  services: new Map([["db", 6379]]) })

Parameters#

Parameter	Type
`image`	`string`
`opts`	{ `command?`: `string`[]; `env?`: `Record`<`string`, `string`>; `name?`: `string`; `ports?`: `number`[]; }
`opts.command?`	`string`[]
`opts.env?`	`Record`<`string`, `string`>
`opts.name?`	`string`
`opts.ports?`	`number`[]

Returns#

Container

tcp()#

function tcp(service): ReadinessProbe;

Ready once a TCP connect to the declared service succeeds.

Parameters#

Parameter	Type
`service`	`string`

Returns#

ReadinessProbe