FissionPlane Quickstart: Your First Sandbox in Minutes

This guide walks you through the full path from a fresh SDK install to running a command inside a live Firecracker microVM. You’ll create a sandbox from the base template, execute a shell command, read the output, and clean up — all in under ten minutes.

Prerequisites

Before you begin, make sure you have:

A running FissionPlane installation on a Kubernetes cluster. If you haven’t installed it yet, follow the Installation guide first.
The control plane URL for your installation (for example, https://api.sandbox.example.com).
An API key issued by your FissionPlane control plane.
The runtime for your chosen SDK: Node.js 20+, Python 3.10+, or Rust 1.97+ with a Tokio runtime.

Ask your platform operator for the control plane URL and an API key if you’re connecting to a shared installation rather than one you deployed yourself.

Install the SDK

Install the FissionPlane SDK for your language.

npm install @fissionplane/sdk

pnpm add @fissionplane/sdk

pip install fissionplane

cargo add fissionplane
cargo add tokio --features macros,rt-multi-thread

Set environment variables

Export your control plane URL and API key so the SDK can find them automatically. Replace the placeholder values with your actual credentials.

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

Every SDK reads both variables at startup, so you won’t need to hard-code credentials into your application code.

Create a client

Instantiate the FissionPlane client. When both environment variables are set, the constructor requires no arguments.

TypeScript
Python
Rust

import { FissionPlane } from '@fissionplane/sdk'

const client = new FissionPlane()

You can also pass credentials directly:

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

from fissionplane import FissionPlane

client = FissionPlane()

You can also pass credentials directly:

client = FissionPlane(
    base_url="https://api.sandbox.example.com",
    api_key="your-api-key",
)

use fissionplane::{ClientOptions, FissionPlane};

let client = FissionPlane::new(ClientOptions::new())?;

You can also pass credentials directly:

let client = FissionPlane::new(
    ClientOptions::new()
        .base_url("https://api.sandbox.example.com")
        .api_key("your-api-key"),
)?;

Create a sandbox

Create a sandbox from the built-in base template. The call returns after a node acknowledges the sandbox — your microVM is ready to accept commands.

TypeScript
Python
Rust

const sandbox = await client.sandboxes.create(
  {
    template: 'base',
    name: 'my-first-sandbox',
    deadline_seconds: 600,
  },
  { idempotencyKey: 'my-first-sandbox-1' },
)

console.log('Sandbox created:', sandbox.sandboxId)

sandbox = client.sandboxes.create(
    "base",
    name="my-first-sandbox",
    deadline_seconds=600,
    idempotency_key="my-first-sandbox-1",
)

print("Sandbox created:", sandbox.sandbox_id)

use fissionplane::models::CreateSandboxRequest;

let sandbox = client
    .sandboxes()
    .create(
        CreateSandboxRequest {
            template: "base".to_owned(),
            name: Some("my-first-sandbox".to_owned()),
            deadline_seconds: Some(600),
            ..Default::default()
        },
        Some("my-first-sandbox-1"),
    )
    .await?;

println!("Sandbox created: {}", sandbox.info.sandbox_id);

Sandboxes are terminated automatically when their deadline expires. The deadline_seconds value above gives the sandbox ten minutes. You can extend the deadline at any time with sandbox.extendDeadline() (TypeScript), sandbox.extend_deadline() (Python), or sandbox.extend_deadline() (Rust).

Run a command

Run a shell command inside the microVM and print its output. commands.run() waits for the process to exit and returns the exit code, stdout, and stderr.

TypeScript
Python
Rust

const result = await sandbox.commands.run('echo', {
  args: ['hello from a microVM'],
  timeoutSeconds: 30,
})

console.log(result.stdout)   // hello from a microVM
console.log(result.exit_code) // 0

result = sandbox.commands.run(
    "echo",
    args=["hello from a microVM"],
    timeout_seconds=30,
)

print(result.stdout)    # hello from a microVM
print(result.exit_code) # 0

use fissionplane::models::RunCommandRequest;

let result = sandbox
    .commands()?
    .run(RunCommandRequest {
        command: "echo".to_owned(),
        args: Some(vec!["hello from a microVM".to_owned()]),
        timeout_seconds: Some(30),
        ..Default::default()
    })
    .await?;

println!("{}", result.stdout);    // hello from a microVM
println!("exit code: {}", result.exit_code); // 0

Delete the sandbox

Delete the sandbox when you’re done. This immediately terminates the microVM and releases node capacity.

TypeScript
Python
Rust

await sandbox.delete()
console.log('Sandbox deleted.')

In production, wrap your commands in a try/finally block to ensure cleanup:

try {
  const result = await sandbox.commands.run('echo', {
    args: ['hello from a microVM'],
  })
  console.log(result.stdout)
} finally {
  await sandbox.delete()
}

sandbox.delete()
print("Sandbox deleted.")

In production, use a try/finally block to ensure cleanup:

try:
    result = sandbox.commands.run(
        "echo", args=["hello from a microVM"]
    )
    print(result.stdout)
finally:
    sandbox.delete()

sandbox.delete().await?;
println!("Sandbox deleted.");

Next steps

Now that your first sandbox is running, explore what else you can do.

Run commands

Stream stdout and stderr in real time, open PTY sessions, and send signals to running processes.

Work with files

Read and write files inside a sandbox, list directories, and watch for filesystem changes.

Expose ports

Make a sandbox port accessible over a private or public HTTPS URL from outside the cluster.

Sandbox lifecycle

Understand how to pause and resume sandboxes, manage deadlines, and use capability tokens.

Get Started

Core Concepts

Guides

SDKs

FissionPlane Quickstart: Your First Sandbox in Minutes

Next steps

Run commands

Work with files

Expose ports

Sandbox lifecycle

​Next steps

Run commands

Work with files

Expose ports

Sandbox lifecycle

Next steps