TypeScript SDK for FissionPlane Sandboxes and Templates

The @fissionplane/sdk package connects your TypeScript and Node.js applications to a self-hosted FissionPlane installation. You can create and control isolated Firecracker microVM sandboxes, run commands, stream process output, manage files, expose ports, and build templates — all from a fully typed client.

Requirements

Before you install the SDK, make sure you have:

Node.js 20 or later
A running FissionPlane control plane and its URL
An API key or OIDC bearer token
A template alias or template artifact ID to use when creating sandboxes

Installation

npm install @fissionplane/sdk

pnpm add @fissionplane/sdk

Configuration

Set your control plane URL and API key as environment variables so the client can pick them up automatically:

export FISSIONPLANE_API_URL="https://api.sandbox.example.com"
export FISSIONPLANE_API_KEY="your-api-key"

Then construct the client with no arguments:

import { FissionPlane } from '@fissionplane/sdk'

const client = new FissionPlane()

You can also pass values directly to the constructor:

const client = new FissionPlane({
  baseUrl: 'https://api.sandbox.example.com',
  apiKey: 'your-api-key',
})

Use accessToken instead of apiKey when authenticating with an OIDC bearer token. When you supply both, apiKey takes precedence. The constructor rejects an empty credential or one that contains whitespace.

Client Options

string

The URL of your FissionPlane control plane. Reads from the FISSIONPLANE_API_URL environment variable when not provided.

string

Your API key. Reads from the FISSIONPLANE_API_KEY environment variable when not provided. Takes precedence over accessToken.

string

An OIDC bearer token. Used when apiKey is not set.

number

default:"60000"

Milliseconds before a request is aborted. Set to 0 to disable timeouts entirely.

number

default:"2"

Number of additional attempts after a failed request. The SDK spaces retries using exponential backoff with full jitter, starting at 250 ms. Set to 0 to disable retries. sandboxes.create() is retried only when you pass an idempotencyKey.

Logger

An object with optional debug, info, warn, and error methods. Receives messages about retries, capability token re-mints, and pagination. Passing console works as-is. The default logger discards all output.

Every request carries User-Agent: fissionplane-typescript/<version>. The SDK exports this string as userAgent if you need it in your own logging or tracing.

Per-Call Overrides

Every method accepts requestTimeoutMs, signal, and headers alongside its own parameters. A per-call requestTimeoutMs replaces the client default for that call only.

const controller = new AbortController()

const sandbox = await client.sandboxes.get('sbx-1', {
  requestTimeoutMs: 5_000,
  signal: controller.signal,
  headers: { 'X-Trace-Id': trace },
})

On commands.attach() and files.watch(), requestTimeoutMs bounds the WebSocket handshake rather than the lifetime of the stream. Pass signal to close the stream itself. Your own headers win over the SDK’s defaults.

Create a Sandbox and Run a Command

Sandbox creation returns after a node acknowledges the sandbox. Use commands.run() when you need the command’s full output after it finishes.

import { FissionPlane } from '@fissionplane/sdk'

const client = new FissionPlane()
const sandbox = await client.sandboxes.create(
  {
    template: 'base',
    name: 'example-job',
    deadline_seconds: 600,
  },
  { idempotencyKey: 'example-job-1' },
)

try {
  const result = await sandbox.commands.run('node', {
    args: ['--eval', "console.log('hello from FissionPlane')"],
    timeoutSeconds: 30,
  })
  console.log(result.stdout)
  console.log(result.exit_code)
} finally {
  await sandbox.delete()
}

commands.run() waits for the process to exit and returns its exit code, standard output, standard error, and an optional truncation flag. Use sandbox.commands.listProcesses() to list supervised processes, and sandbox.commands.kill(pid, 'SIGTERM') to send a signal to one.

Background Processes and PTY

When you need to follow output in real time or keep stdin open, start a background process with commands.start(). Pass a pty option to allocate a pseudo-terminal.

const child = await sandbox.commands.start('bash', {
  pty: { cols: 120, rows: 40 },
})
const attachment = child.attach()
attachment.sendInput('pwd\n')

for await (const event of attachment) {
  if (event.type === 'stdout') console.log(event.data)
  if (event.type === 'exit') break
}

The attachment is an async iterable of typed events. Break out of the loop at any time to stop consuming output.

Filesystem Operations

Filesystem calls go directly to the sandbox data plane. You can create directories, upload content, list entries, and watch for changes.

await sandbox.files.makeDir('/workspace')
await sandbox.files.write(
  '/workspace/input.txt',
  new TextEncoder().encode('hello'),
)
const entries = await sandbox.files.list('/workspace')
const watch = sandbox.files.watch('/workspace', { recursive: true })

Sandbox Lifecycle

A sandbox moves through four visible states: running, paused, terminated, and failed.

await sandbox.pause()
await sandbox.resume({ deadlineSeconds: 600 })
await sandbox.extendDeadline(900)
await sandbox.delete()

pause() snapshots the sandbox and releases the underlying node capacity. resume() restores the snapshot on a node and gives the sandbox a new epoch.

Capability tokens are scoped to a single sandbox epoch. After resume(), the SDK automatically replaces the token on the handle. Handles returned by sandboxes.get() or sandboxes.iterate() carry no token — call sandbox.mintToken() before issuing commands on them. When the data plane rejects an expired token, the SDK mints a replacement and replays the request once automatically. Streams opened by commands.attach() and files.watch() require a valid token up front because a rejected WebSocket handshake is opaque to the SDK.

Pass an idempotencyKey to sandboxes.create() so that retries return the same sandbox instead of creating a duplicate.

Port Exposure

Every sandbox port is private by default, accessible only with a capability token. Make a port public only when anonymous access is required.

const exposure = await sandbox.ports.expose(3000, 'public')
console.log(exposure.url)

const records = await sandbox.ports.list()
await sandbox.ports.unexpose(3000)

unexpose() removes the exposure record and returns the port to private access.

Build and Use a Template

Template builds run asynchronously on your FissionPlane installation. Start a build, wait for it to finish, then reference the template by alias.

const build = await client.templates.build({
  image: 'node:22',
  alias: 'node-tools',
  steps: [{ command: 'npm install --global pnpm' }],
})

const template = await build.wait({ timeoutMs: 10 * 60 * 1000 })
const sandbox = await client.sandboxes.create({ template: 'node-tools' })

Stream build output with build.logs(offset). Pass nextOffset from each response into the next call to avoid re-reading lines. Use client.templates.getBuild(buildId) to reconnect to a build started in a previous process.

List Sandboxes

Read a single page of sandboxes filtered by state or metadata:

const page = await client.sandboxes.list({
  state: 'running',
  metadata: { team: 'tools' },
  limit: 20,
})

Use iterate() to walk every page automatically. The SDK fetches the next page only when the previous one is exhausted, and it follows each page’s nextCursor until the collection ends.

for await (const sandbox of client.sandboxes.iterate({ state: 'running' })) {
  console.log(sandbox.sandboxId)
}

iterate() accepts the same filters as list() except cursor. Break out of the loop to stop early.

Error Handling

All SDK errors inherit from FissionPlaneError. HTTP errors carry status, code, retryable, and requestId when the server provides them.

import { FissionPlaneError, RateLimitError } from '@fissionplane/sdk'

try {
  await client.sandboxes.create({ template: 'base' })
} catch (error: unknown) {
  if (error instanceof RateLimitError && error.retryable) {
    console.error(`retry later; request ID: ${error.requestId}`)
  } else if (error instanceof FissionPlaneError) {
    console.error(error.code, error.message)
  } else {
    throw error
  }
}

The package also exports typed errors for authentication failures, authorization denials, missing resources, lifecycle conflicts, expired snapshots, command timeouts, and failed template builds.

Control Plane and Data Plane

The control plane manages sandboxes, ports, tokens, and templates. The sandbox data plane runs commands, streams process I/O, and accesses files. The SDK sends your API key or OIDC token to the control plane. It sends a short-lived capability token to the sandbox data plane, stored on the sandbox handle. The data-plane agent uses port 50000 by default. Set agentPort in the client options only when your installation uses a different port. You can also supply a custom fetch implementation in the client options. client.api exposes the generated, fully typed HTTP client for operations not wrapped by the SDK. Those calls carry your credentials, the SDK User-Agent, and the request timeout, but not the retry loop.

@fissionplane/sdk is version 0.0.1. The public API is unstable and may change without notice until the project publishes a stable release.

Get Started

Core Concepts

Guides

SDKs

TypeScript SDK for FissionPlane Sandboxes and Templates

Requirements

Installation

Configuration

Client Options

Per-Call Overrides

Create a Sandbox and Run a Command

Background Processes and PTY

Filesystem Operations

Sandbox Lifecycle

Port Exposure

Build and Use a Template

List Sandboxes

Error Handling

Control Plane and Data Plane

​Requirements

​Installation

​Configuration

​Client Options

​Per-Call Overrides

​Create a Sandbox and Run a Command

​Background Processes and PTY

​Filesystem Operations

​Sandbox Lifecycle

​Port Exposure

​Build and Use a Template

​List Sandboxes

​Error Handling

​Control Plane and Data Plane

Requirements

Installation

Configuration

Client Options

Per-Call Overrides

Create a Sandbox and Run a Command

Background Processes and PTY

Filesystem Operations

Sandbox Lifecycle

Port Exposure

Build and Use a Template

List Sandboxes

Error Handling

Control Plane and Data Plane