Oblien SDK

Cloud workspaces that boot in milliseconds and run anything.

Oblien gives you hardware-isolated microVMs — each with its own kernel, its own memory, and full root access. Use them to give an AI agent a live environment, deploy a service with a public URL, run untrusted code in a throwaway sandbox, or spin up a dev machine you can SSH into. The workspace is the only primitive. What it becomes is up to you.

This is the official TypeScript SDK. It covers the full Oblien API surface.

Documentation: https://oblien.com/docs

Platform

Oblien is a workspace platform. Every workspace is a microVM that boots in under a second from any Docker image. Workspaces can be temporary (auto-delete after a TTL) or permanent (run indefinitely). They can be air-gapped or wired to other workspaces over a private internal network. They can expose ports to the internet with automatic TLS — or stay completely invisible.

The architecture is split into two planes:

• Control plane (api.oblien.com) — Create, configure, start, stop, snapshot, and destroy workspaces. Manage networking, domains, pages, namespaces, and billing.
• Data plane (workspace.oblien.com) — Interact with a running workspace's filesystem, execute commands, open terminal sessions, watch files, and stream events over WebSocket.

The SDK wraps both planes in a single client.

What people build with it

• AI agent environments — A permanent workspace is the agent's home. It creates short-lived sandboxes on demand for tasks, user code, or deployments.
• Service hosting — Run an API server, a queue worker, or a database. Map it to a custom domain.
• Static pages — Deploy build output from a workspace to the edge CDN. No running VM required.
• Remote development — SSH into a workspace, install your stack, expose a port for live preview.
• Per-user environments — One workspace per customer with scoped networking, credit quotas, and full isolation.
• Enterprise routing — Route subdomains to external upstreams through the edge proxy.

Install

npm install oblien

Requires Node.js 18 or later. Zero runtime dependencies.

Quick start

import Oblien from 'oblien';

const client = new Oblien({
  clientId: process.env.OBLIEN_CLIENT_ID,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET,
});

// Create a workspace
const workspace = await client.workspaces.create({
  image: 'node-20',
  mode: 'permanent',
  cpus: 2,
  memory_mb: 4096,
});

// Connect to the runtime — filesystem, exec, terminal
const rt = await client.workspaces.runtime(workspace.id);

// Run a command
const result = await rt.exec.run(['node', '--version']);
console.log(result.stdout);

// Read a file
const file = await rt.files.read({ filePath: '/etc/os-release' });
console.log(file.content);

SDK structure

client
├── workspaces          Control-plane workspace CRUD + power + sub-resources
│   ├── lifecycle       Permanent/temporary mode, TTL, ping
│   ├── network         Firewall, private links, outbound IP
│   ├── ssh             SSH enable/disable, password/key
│   ├── publicAccess    Expose ports with public URLs
│   ├── domains         Custom domains with automatic SSL
│   ├── resources       CPU, memory, disk allocation
│   ├── snapshots       Snapshots and versioned archives
│   ├── workloads       Managed background processes
│   ├── metrics         Live stats, VM info/config
│   ├── usage           Credit usage and activity tracking
│   ├── metadata        Key-value metadata store
│   ├── apiAccess       Runtime API tokens (gateway JWT / raw)
│   ├── logs            Boot and command logs
│   └── images          Available base images
│
├── pages               Static pages — deploy to the edge CDN from any workspace
├── namespaces          Group workspaces, enforce resource limits and quotas
├── edgeProxy           Enterprise reverse proxy — route subdomains to upstreams
├── domain              Pre-flight checks — slug availability + DNS verification
│
└── workspace(id)       Scoped handle — all methods pre-filled with a workspace ID

Workspaces

const ws = client.workspaces;

// CRUD
const workspace = await ws.create({ image: 'node-20' });
const { workspaces } = await ws.list();
const data = await ws.get(workspace.id);
await ws.update(workspace.id, { name: 'my-api' });
await ws.delete(workspace.id);

// Power
await ws.start(id);
await ws.stop(id);
await ws.restart(id);
await ws.pause(id);
await ws.resume(id);

Sub-resources are accessed through namespaces on the workspaces object — ws.lifecycle, ws.network, ws.domains, etc. See the API reference for full details on each.

Scoped handle

Bind to a single workspace so you don't have to pass the ID every time:

const handle = client.workspace('ws_abc');

await handle.start();
const rt = await handle.runtime();
await rt.exec.run(['npm', 'test']);
await handle.stop();

Runtime (data plane)

The runtime connects to a running workspace and gives you direct access to its filesystem, command execution, terminal sessions, code search, and file watchers.

const rt = await client.workspaces.runtime('ws_abc');

This enables the Runtime API server (if needed), fetches a gateway JWT, and returns a Runtime instance. The token is cached — subsequent calls for the same workspace return instantly.

| Namespace | What it does | |-----------|-------------| | rt.files | List, read, write, stat, mkdir, delete, stream directory trees | | rt.exec | Run commands, stream output, list/kill tasks, send stdin | | rt.terminal | Create PTY sessions, get scrollback, close sessions | | rt.search | Content search (ripgrep) and filename search | | rt.watcher | Watch directories for real-time file change events | | rt.ws() | WebSocket — persistent connection for terminal I/O and watcher events |

See the Runtime API docs for full endpoint reference.

Pages

Deploy static files from a workspace to the edge CDN. The workspace can stop or be deleted after export — the page stays live with automatic TLS.

// Deploy a page
const { page } = await client.pages.create({
  workspace_id: 'ws_abc',
  path: '/app/dist',
  name: 'my-app',
});

// Re-deploy with fresh files
await client.pages.deploy(page.slug, {
  workspace_id: 'ws_abc',
  path: '/app/dist',
});

// Custom domain
await client.pages.connectDomain(page.slug, { domain: 'app.example.com' });

// Toggle
await client.pages.disable(page.slug);
await client.pages.enable(page.slug);

See the Pages docs for concepts and the Pages API for the full reference.

Domains

Pre-flight checks before connecting custom domains or claiming slugs. These are standalone — not scoped to a specific workspace or page.

// Check if a slug is available
const { available, url } = await client.domain.checkSlug({ slug: 'my-app' });

// Verify DNS for a custom domain
const { verified, cname, ownership, errors, required_records } = await client.domain.verify({
  domain: 'app.example.com',
  resource_id: 'ws_abc',
});

if (!verified) {
  console.log(errors);
  console.log(required_records);
}

Standard plans require both edge DNS and TXT ownership. Enterprise custom-domain grants can verify with edge DNS only.

Namespaces

Group workspaces into isolated namespaces with resource limits, spending quotas, and lifecycle controls.

const ns = await client.namespaces.create({
  name: 'production',
  resource_limits: { max_workspaces: 50, max_cpus: 100 },
});

await client.namespaces.setQuota(ns.id, {
  period: 'monthly',
  max_credits: 500,
  overdraft_action: 'stop',
});

const { namespaces } = await client.namespaces.list();

See the Namespaces API for the full reference.

Edge Proxy

Enterprise-only reverse proxy — route subdomains to external upstreams through the edge.

const { proxy } = await client.edgeProxy.create({
  name: 'staging-api',
  slug: 'staging-api',
  domain: 'edge.example.com',
  target: 'https://internal-staging.example.com:8080',
});

await client.edgeProxy.disable(proxy.id);
await client.edgeProxy.enable(proxy.id);

See the Edge Proxy docs for details.

Error handling

Every API error is an instance of OblienError with typed subclasses. The SDK preserves the machine-readable code, human-readable message, optional details, and optional requestId from the API response.

import {
  OblienError,
  NotFoundError,
  RateLimitError,
  PaymentRequiredError,
} from 'oblien';

try {
  await client.workspaces.get('ws_nonexistent');
} catch (err) {
  if (err instanceof NotFoundError) { /* 404 */ }
  if (err instanceof RateLimitError) { /* 429 — back off */ }
  if (err instanceof PaymentRequiredError) { /* 402 — quota exceeded */ }
  if (err instanceof OblienError) {
    console.error(err.code, err.message, err.details, err.requestId);
  }
}

| Error class | HTTP | When | |-------------|------|------| | AuthenticationError | 401 | Invalid or missing credentials | | PaymentRequiredError | 402 | Credit quota exceeded | | NotFoundError | 404 | Resource does not exist | | ConflictError | 409 | Resource in wrong state | | ValidationError | 422 | Invalid parameters | | RateLimitError | 429 | Too many requests |

Configuration

const client = new Oblien({
  clientId: 'your_client_id',       // required
  clientSecret: 'your_client_secret', // required
  baseUrl: 'https://api.oblien.com',  // optional, default
});

Get your API keys from the dashboard.

TypeScript

Written in TypeScript with full type declarations shipped. All request parameters, response shapes, and event types are exported:

import type {
  WorkspaceCreateParams, WorkspaceData,
  PageCreateParams, PageData,
  CheckSlugParams, VerifyDomainParams,
  EdgeProxyCreateParams,
  ExecStreamEvent, WSTerminalEvent,
} from 'oblien';

Requirements

• Node.js 18+
• TypeScript 5.0+ (if using TypeScript)
• ESM ("type": "module" in your package.json, or use dynamic import())

Links

• Documentation
• Quickstart
• SDK setup guide
• API reference
• Runtime API
• Dashboard

License

MIT