Oblien SDK

Cloud workspaces (sandboxes) 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 across both planes:

• Control plane (api.oblien.com) — create, configure, power, snapshot, destroy workspaces; manage networking, domains, pages, namespaces, billing.
• Data plane (workspace.oblien.com) — a running workspace's filesystem, exec, terminal, watchers, and WebSocket events.

Hosted docs: oblien.com/docs

Install

npm install oblien

Node.js 18+, ESM. 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', cpus: 2, memory_mb: 4096 });

// Connect to the runtime — filesystem, exec, terminal
const rt = await client.workspaces.runtime(workspace.id);
const result = await rt.exec.run(['node', '--version']);
console.log(result.stdout);

Features

The client wraps every part of the platform. Each feature has a deep-dive page in docs/.

| Feature | Accessor | What it does | Guide | |---------|----------|--------------|-------| | Workspaces | client.workspaces, client.workspace(id) | microVM CRUD, power, and 14 sub-resources (network, ssh, snapshots, …) | docs/workspaces | | Runtime | client.workspaces.runtime(id) | Data plane: files, exec, terminal, search, watchers, WebSocket | docs/runtime | | Pages | client.pages | Deploy static files to the edge CDN with automatic TLS | docs/pages | | Namespaces | client.namespaces | Group workspaces; resource limits, quotas, per-namespace usage | docs/namespaces | | Domains | client.domain | Slug/DNS pre-flight, route listing, SSL certs + auto-renew | docs/domains | | Edge Proxy | client.edgeProxy | Reverse-proxy subdomains to verified external upstreams | docs/edge-proxy | | Edge Tunnel | client.edgeTunnel | Expose a local port to the internet (ngrok-style) | docs/edge-tunnel | | Notifications | client.notifications | Mobile push via per-workspace virtual send tokens | docs/notifications | | Webhooks | client.webhooks | Subscribe to events; HMAC-signed, namespace-scopable | docs/webhooks | | Analytics | client.analytics | Edge traffic — requests, bandwidth, geo, live stream | docs/analytics | | Scoped Tokens | client.tokens | Short-lived, per-tenant scoped JWTs | docs/tokens | | Errors | import { OblienError, … } | Typed error classes for every HTTP status | docs/errors |

Map at a glance

client
├── workspaces        microVM CRUD + power + sub-resources    → docs/workspaces.md
│   └── runtime(id)   files · exec · terminal · search · ws   → docs/runtime.md
├── workspace(id)     scoped handle (ID pre-filled)
├── pages             static deploys to the edge CDN          → docs/pages.md
├── namespaces        grouping · limits · quotas · usage      → docs/namespaces.md
├── domain            slug/DNS checks · routes · SSL          → docs/domains.md
├── edgeProxy         subdomain → verified upstream           → docs/edge-proxy.md
├── edgeTunnel        local port → public URL                 → docs/edge-tunnel.md
├── notifications     mobile push (virtual tokens)            → docs/notifications.md
├── webhooks          event subscriptions                     → docs/webhooks.md
├── analytics         edge traffic metrics                     → docs/analytics.md
└── tokens            short-lived scoped tokens                → docs/tokens.md

Also included

• CLI — npx oblien … (auth, workspaces, exec, scp, terminal, tunnels, …). See CLI docs.
• MCP server — oblien-mcp exposes the SDK as Model Context Protocol tools for agents. See MCP docs.

Configuration

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

// Or a short-lived scoped token (see docs/tokens.md):
const scoped = new Oblien({ token });

Get API keys from the dashboard.

TypeScript

Written in TypeScript with full declarations shipped. Every request param, response shape, and event type is exported:

import type {
  WorkspaceCreateParams, WorkspaceData,
  NamespaceUsageUnits, EdgeProxyCreateParams,
  WebhookEvent, ExecStreamEvent,
} from 'oblien';

Links

• Documentation · Quickstart · API reference · Runtime API · Dashboard

License

MIT