TypeScript SDK Quickstart: Deploy and Manage Cubes

You can provision a fully isolated microVM, configure networking, and automate infrastructure from your TypeScript code in minutes. A TypeScript SDK quickstart eliminates boilerplate, gives you editor autocomplete for every API call, and removes the friction between writing code and running it on real infrastructure.

TL;DR:

• Install @krovacloud/sdk or @openai/agents and authenticate with an API key scoped to your space.
• Use client.cubes.create() to provision a Cube (or a sandbox agent) in seconds.
• Chain lifecycle methods (powerOff, wake, delete) to automate workflows.
• Sandbox agents let untrusted code run in isolation while your control plane stays safe.

What Is a TypeScript SDK Quickstart?

A TypeScript SDK quickstart is a guide that gets you from zero to running your first infrastructure call in the shortest time, with the least friction. Install a typed client, load an API key, and start calling methods. Your editor knows every parameter, validates types before you deploy, and shows you response shapes as you write.

For infrastructure, this matters. A single misconfigured request can spin up resources you'll be billed for or expose a port to the internet when you meant it private. A typed SDK catches those mistakes before the code runs. The TypeScript SDK documentation and OpenAI Agents SDK both publish fully generated types from their API specs.

Getting Started with the TypeScript SDK

Start by installing the SDK. If you're building on Krova Cloud infrastructure, install the Krova TypeScript SDK:

npm install @krovacloud/sdk

The only runtime dependency is openapi-fetch; TypeScript declarations ship bundled. It requires Node.js 18 or newer and runs on Deno, Bun, edge functions, and any runtime with WHATWG fetch.

Next, create an API key. Go to your Krova Cloud dashboard, navigate to Settings → API keys, and generate a new key scoped to the space you want to access. Keys look like kro_... and inherit the permissions of the membership that created them. Store the key in an environment variable:

export KROVA_KEY="kro_your_api_key_here"

Load it and instantiate the client:

import { KrovaClient } from "@krovacloud/sdk";

const client = new KrovaClient({
  apiKey: process.env.KROVA_KEY,
});

The client throws if apiKey is missing. If your setup runs behind a gateway that expects a bearer token instead of an X-API-KEY header, pass authScheme: "bearer". Errors always include the HTTP status, the API message, an optional error code, and a requestId for support reference.

Every space-scoped call takes the spaceId as its first argument. Find your space ID in the dashboard or resolve it once and reuse it.

Provisioning Your First Cube with the SDK

Creating a Cube is one method call. A Cube is a Firecracker microVM with its own Linux kernel, full root access, and per-minute billing. You choose the vCPU, RAM, disk, operating system image, and SSH key.

const cube = await client.cubes.create("YOUR_SPACE_ID", {
  name: "my-first-cube",
  cpuCount: 2,
  memoryMb: 2048,
  diskGb: 30,
  image: "ubuntu-24.04",
  sshPublicKey: "ssh-rsa AAAA...",
});

console.log(cube.id, cube.status, cube.sshPort);

The response includes the Cube's ID, current status, SSH port, and public IP if assigned. Cubes boot in seconds because Firecracker is lightweight.

Once it's running, list every Cube in your space:

const cubes = await client.cubes.list("YOUR_SPACE_ID");
console.log(cubes.map((c) => ({ id: c.id, name: c.name, status: c.status })));

Fetch a single Cube by ID:

const cube = await client.cubes.get("YOUR_SPACE_ID", "cube_abc123");

All responses are fully typed, so your editor autocompletes properties and TypeScript catches typos before runtime.

Managing Cube Lifecycle and Resources

Cubes have two main states: running and stopped. Power off a Cube to pause compute charges; disk and snapshots stay around. Billing resumes the moment you wake it:

await client.cubes.powerOff("YOUR_SPACE_ID", cube.id);
// Compute charges stop instantly.

await client.cubes.wake("YOUR_SPACE_ID", cube.id);
// Charges resume when it boots.

A cold restart re-reads the host kernel, which a reboot inside the Cube cannot do:

await client.cubes.restart("YOUR_SPACE_ID", cube.id);

Resize a running Cube to add vCPU and RAM, or grow its disk. New resources apply immediately and billing continues at the new rate:

await client.cubes.update("YOUR_SPACE_ID", cube.id, {
  cpuCount: 4,
  memoryMb: 8192,
});

Clean up when you're done:

await client.cubes.delete("YOUR_SPACE_ID", cube.id);

Mutating endpoints (POST/DELETE) are rate-limited to 10 requests per 60 seconds per client IP. The SDK automatically retries 429 and 503 responses, honoring Retry-After headers, so transient failures don't break your automation.

Snapshots let you freeze a Cube's entire state and spawn fresh copies later. This pattern is essential for CI runners, ephemeral dev environments, and AI agent sandboxes. Create a snapshot, then boot a new Cube from it for each job or agent run, as shown in the TypeScript SDK quickstart. Query metrics and logs over SSH or the API, tear it down when done. Storage costs only a few cents per snapshot per month.

Sandbox Agents and AI Workloads in TypeScript

If you're running untrusted code, AI agents that execute shell commands, or ephemeral CI pipelines, sandboxes matter. The OpenAI Agents SDK sandbox agents guide describes the boundary clearly: the harness is your control plane (orchestration, auth, audit logs, recovery), and the sandbox is the execution plane (files, commands, dependencies, ports).

Keeping those separate is the whole point. Your application keeps sensitive logic in trusted infrastructure; the sandbox stays focused on model-directed work with narrow permissions and mounts, a split the TypeScript SDK quickstart sets up by default. A Cube gives you VM-grade isolation. Each Cube runs its own Linux kernel behind a per-Cube sandbox, so one tenant's kernel exploit never reaches another. That differs from container-based sandboxes that share the host kernel.

When you need a workspace for agents, create a base Cube as shown in the TypeScript SDK quickstart, install your agent runtime and dependencies, snapshot it, then spin up fresh copies for each agent run. Query metrics, stream logs, and tear the Cube down when the job finishes. Billing stops the moment you power off, so ephemeral workloads cost only what they actually use.

The OpenAI Agents SDK also ships a TypeScript SDK that integrates Sandbox Agents for LLM-driven work. If you're building multi-agent workflows where agents need filesystem access and shell command execution, Temporal's OpenAI Agents SDK integration lets you run agents as Temporal Workflows, with durable retries and recovery handled automatically.

Most people get the harness/compute split wrong by running orchestration inside the sandbox. Don't. Keep your control plane (auth, billing, approval gates, logs) in trusted infrastructure. The sandbox is an execution tool, not a control tool.

FAQ

How Do I Authenticate the TypeScript SDK?

Create an API key in your Krova Cloud dashboard (Settings → API keys), scoped to the space you want to access. Store it in an environment variable and pass it to new KrovaClient({ apiKey: process.env.KROVA_KEY }). Keys inherit the permissions of the membership that created them and are not reusable across spaces.

What's the Difference Between a Cube and a Container for AI Agent Sandboxes?

A Cube runs its own Linux kernel in a per-Cube jailer sandbox, so one tenant's kernel-level exploit cannot reach another. A container shares the host kernel with every other tenant on the machine. Cubes give you VM-grade isolation with container-like speed and boot in seconds using Firecracker, the same technology AWS uses for Lambda and Fargate. Choose a Cube if your agents run untrusted code or you need strict isolation between jobs — the TypeScript SDK quickstart walks through launching your first one.

Can I Use the TypeScript SDK with OpenAI Agents?

Yes. The @openai/agents package includes a TypeScript SDK that works with OpenAI's Agents API and Sandbox Agents. If you're building sandbox agents with OpenAI's models, follow their TypeScript SDK quickstart: install @openai/agents, authenticate with your OpenAI API key, and call the sandbox methods directly. Krova's @krovacloud/sdk is for provisioning and managing Cubes; OpenAI's SDK is for orchestrating agents and model calls.

How Much Does It Cost to Run Ephemeral Cubes for Agent Jobs?

Cubes — including the one you launch in the TypeScript SDK quickstart — are billed by the minute, with per-minute pricing starting at $0.004/hour for a 1 vCPU, 1 GB RAM, 10 GB disk Cube (about $2.92/month if running 24/7). Billing stops the instant you power off, so a 5-minute agent job on a 2 vCPU, 2 GB Cube costs roughly 1-2 cents. See Krova Cloud pricing for exact rates.