---
name: oblien-platform
description: >-
  Oblien platform guide - what workspaces are (Firecracker microVMs), architecture, security, authentication (API keys vs tokens), SDK setup with code examples, quickstart, lifecycle modes, images, resource pools, billing, webhooks, and common workflows for creating and connecting workspaces.
license: MIT
compatibility:
  - claude-code
  - cursor
  - openclaw
  - goose
  - jetbrains-ai
metadata:
  author: oblien
  version: 1.0.0
  source: https://oblien.com/docs
---

# Oblien Platform Guide

This skill gives you the foundational knowledge to work with the Oblien platform. It covers what workspaces are, how authentication works, how to set up the SDK, and the key concepts you need before using the APIs.

## Quick orientation

- **Workspaces** are Firecracker microVMs - real Linux VMs (not containers) with their own kernel, network, and filesystem
- **Two APIs**: Control-plane (`api.oblien.com`) for managing workspaces, and Runtime API (`workspace.oblien.com` or `10.x.x.x:9990`) for operating inside them
- **Two auth methods**: API keys (server-side, for control-plane) and tokens (Gateway JWT or raw, for Runtime API)
- **Images** are base environments (Node, Python, Go, Ubuntu, etc.) your workspace boots from
- **Modes**: Permanent (always running, auto-restart) or temporary (TTL, auto-expire)

## Common workflows

### Create a workspace and run code in it

```typescript
import Oblien from 'oblien';

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

// 1. Create
const ws = await client.workspaces.create({
  name: 'my-app',
  image: 'node-20',
  config: { cpus: 2, memory_mb: 2048 },
});

// 2. Enable Runtime API
const { token } = await client.workspaces.apiAccess.enable(ws.id);

// 3. Use runtime to run code
const rt = await client.workspaces.runtime(ws.id);
const result = await rt.exec.run({ cmd: ['node', '-e', 'console.log("hello")'] });
```

### Connect two workspaces

```typescript
// Enable Runtime API on target
await client.workspaces.apiAccess.enable('ws_target');

// Create private link: caller → target
await client.workspaces.network.update('ws_target', {
  private_link_ids: ['ws_caller'],
});

// Get direct connection details
const raw = await client.workspaces.apiAccess.rawToken('ws_target');
// raw.ip = "10.40.0.12", raw.token = "a1b2c3...", raw.port = 9990
```

---

The reference below covers architecture, authentication, SDK setup, and platform concepts in detail.

## Reference files

Each section below is loaded on demand. Read only what you need for the current task.

- **[Architecture](references/architecture.md)** (127 lines)
- **[Security & Privacy](references/security.md)** (234 lines)
- **[Use Cases](references/use-cases.md)** (570 lines)
- **[Quickstart](references/quickstart.md)** (155 lines)
- **[Authentication](references/authentication.md)** (144 lines)
- **[SDK Setup](references/sdk-setup.md)** (320 lines)
- **[Images](references/images.md)** (118 lines)
- **[Lifecycle Modes](references/modes.md)** (186 lines)
- **[Resource Pools](references/resource-pools.md)** (119 lines)
- **[Billing & Credits](references/billing.md)** (93 lines)
- **[Webhooks](references/webhooks.md)** (135 lines)

### Quick search

Find specific endpoints, methods, or parameters across all references:

```bash
grep -ri "keyword" references/
```