oblien 1.3.0 → 2.0.1

package/README.md

@@ -1,574 +1,634 @@
-# Oblien Core SDK
+# Oblien SDK
 
-Complete Node.js SDK for the Oblien AI Platform. Manage agents, chat sessions, sandboxes, namespaces, and more.
+Cloud workspaces that boot in milliseconds and run anything.
 
-## Installation
+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.
 
-```bash
-npm install oblien
-```
-
-## Quick Start
-
-```javascript
-// Import client
-import { OblienClient } from 'oblien';
-
-// Import modules (tree-shakeable)
-import { OblienAgents } from 'oblien/agents'; // agent creation
-import { OblienChat } from 'oblien/chat'; // agent chat managment
-import { OblienSandboxes } from 'oblien/sandbox'; // sandbox for agent code execution
-import { OblienEmbeddings } from 'oblien/embeddings'; // embeddings store for semantic search
-import { OblienSearch } from 'oblien/search'; // search gateway for your agent
-import { OblienIcons } from 'oblien/icons'; // sematic based icons fetch
-import { OblienNamespaces } from 'oblien/namespaces'; // user and guest management 
-import { OblienCredits } from 'oblien/credits'; // credits managemnt for your user
-import { OblienCDN } from 'oblien/cdn'; // cdn upload for your app
-import { OblienBrowser } from 'oblien/browser'; // browser api for scrap or any task
-import { OblienDeployments } from 'oblien/deployments'; // deployments gateway
-
-// Initialize client
-const client = new OblienClient({
-    clientId: 'your-client-id',
-    clientSecret: 'your-client-secret'
-});
+This is the official TypeScript SDK. It covers the full Oblien API surface: workspace lifecycle, networking, snapshots, workloads, metrics, SSH, public access, and the in-workspace runtime (files, exec, terminal, search, watchers, WebSocket).
 
-// Use modules
-const agents = new OblienAgents(client);
-const chat = new OblienChat(client);
-const sandboxes = new OblienSandboxes(client);
-const search = new OblienSearch(client);
-const icons = new OblienIcons(client);
-```
+**Documentation:** [https://oblien.com/docs](https://oblien.com/docs)
 
 ---
 
-## Modules Overview
+## Platform
 
-### 🤖 Agents Module
+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 through Oblien's edge proxy with automatic TLS -- or stay completely invisible.
 
-Manage AI agents with settings, tools, and analytics.
+The architecture is split into two planes:
 
-```javascript
-import { OblienAgents } from 'oblien/agents';
+- **Control plane** (`api.oblien.com`) -- Create, configure, start, stop, snapshot, and destroy workspaces. Manage networking, firewall rules, SSH keys, workloads, images, billing, and metadata.
+- **Data plane** (`workspace.oblien.com`) -- Interact with a running workspace's filesystem, execute commands, open terminal sessions, watch files, and stream events over WebSocket.
 
-const agents = new OblienAgents(client);
+The SDK wraps both planes in a single client.
 
-// Create agent
-const agent = await agents.create({
-    name: 'Support Agent',
-    namespace: 'production',
-    prompts: {
-        identity: 'You are a helpful assistant.'
-    }
-});
+### What people build with it
 
-// Configure settings
-const agentInstance = agents.agent(agent.agentId);
-await agentInstance.settings.updateModelConfig({
-    model: 'oblien-master',
-    temperature: 0.8
-});
+- **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 as a permanent workspace. Map it to a custom domain.
+- **Remote development** -- SSH into a workspace, install your stack, expose a port for live preview.
+- **CI/CD** -- Spin up ephemeral workspaces per build, run tests in full isolation, auto-destroy when done.
+- **Code sandboxes** -- Air-gapped throwaway VMs that auto-delete after a TTL. No internet, no persistence.
+- **Per-user environments** -- One workspace per customer with scoped networking, credit quotas, and full isolation.
 
-// Assign tools
-await agentInstance.settings.updateTools(['web-search', 'calculator']);
+---
 
-// Get analytics
-const overview = await agentInstance.getOverview({ days: 7 });
-```
+## Install
 
-**Features:**
-- ✅ CRUD operations (create, read, update, delete)
-- ✅ Settings management (5 sections: switches, model, tools, guest limits, context)
-- ✅ Tools management (list, search, create, validate)
-- ✅ Analytics & monitoring
-- ✅ Namespace support
-- ✅ User management
+```bash
+npm install oblien
+```
 
-📖 [Full Documentation](./docs/AGENTS_COMPLETE.md) | 💡 [Examples](./examples/agents-complete-example.js)
+Requires Node.js 18 or later. Zero runtime dependencies.
 
 ---
 
-### 💬 Chat Module
+## Quick start
 
-Create sessions, send messages, and manage guests with streaming support.
+```typescript
+import Oblien from 'oblien';
 
-```javascript
-import { OblienChat } from 'oblien/chat';
+const client = new Oblien({
+  clientId: process.env.OBLIEN_CLIENT_ID,
+  clientSecret: process.env.OBLIEN_CLIENT_SECRET,
+});
 
-const chat = new OblienChat(client);
+const ws = client.workspaces;
 
-// Create session
-const session = await chat.createSession({
-    agentId: 'agent-id',
-    namespace: 'production'
+// Create a workspace
+const workspace = await ws.create({
+  image: 'node-20',
+  mode: 'permanent',
+  config: { cpus: 2, memory_mb: 4096 },
 });
 
-// Send message with streaming
-await chat.send({
-    token: session.token,
-    message: 'Tell me about AI',
-    stream: true,
-    onChunk: (data) => console.log(data)
-});
+// Start it
+await ws.start(workspace.id);
 
-// Upload files
-const uploadResult = await chat.upload({
-    token: session.token,
-    files: fileArray
-});
+// Connect to the runtime -- filesystem, exec, terminal
+const rt = await ws.runtime(workspace.id);
 
-// Send message with uploaded files
-await chat.send({
-    token: session.token,
-    message: 'Analyze these files',
-    uploadId: uploadResult.uploadId
-});
+// Run a command
+const result = await rt.exec.run(['node', '--version']);
+console.log(result.stdout);
 
-// Create guest session
-const guestSession = await chat.createGuestSession({
-    ip: '192.168.1.1',
-    fingerprint: 'abc123',
-    agentId: 'agent-id'
-});
+// Read a file
+const file = await rt.files.read({ filePath: '/etc/os-release' });
+console.log(file.content);
 
-// Get guest usage
-const usage = await chat.getGuestUsage(guestSession.token);
+// Expose port 3000 to the internet
+await ws.publicAccess.expose(workspace.id, { port: 3000 });
 ```
 
-**Features:**
-- ✅ Session management (create, list, delete)
-- ✅ Message sending with streaming support
-- ✅ File uploads for agent analysis
-- ✅ Guest sessions with IP + fingerprint tracking
-- ✅ Guest usage monitoring and rate limiting
-- ✅ Hybrid mode (works with token or client credentials)
-- ✅ Cache statistics for monitoring
+---
 
-📖 [Full Documentation](./docs/CHAT.md) | 💡 [Examples](./examples/chat-example.js)
+## Architecture
 
----
+### Client and workspaces
 
-### 📦 Sandboxes Module
+```typescript
+import Oblien from 'oblien';
 
-Manage cloud sandboxes (containerized environments).
+const client = new Oblien({ clientId, clientSecret });
+const ws = client.workspaces;
+```
 
-```javascript
-import { OblienSandboxes } from 'oblien/sandbox';
+`client.workspaces` is the entry point for all control-plane operations. It provides CRUD methods, power controls, and 13 sub-resource namespaces:
+
+| Namespace | Description |
+|-----------|-------------|
+| `ws.lifecycle` | Permanent/temporary mode, TTL, ping, destroy |
+| `ws.network` | Firewall rules, private links, outbound IP |
+| `ws.ssh` | Enable SSH, set password or public key |
+| `ws.publicAccess` | Expose and revoke public ports |
+| `ws.resources` | CPU, memory, disk allocation |
+| `ws.snapshots` | Create, restore, archive, and manage snapshots |
+| `ws.workloads` | Managed background processes with log streaming |
+| `ws.metrics` | Live CPU/memory/disk/network stats, VM info and config |
+| `ws.usage` | Credit usage, activity tracking |
+| `ws.metadata` | Key-value metadata store |
+| `ws.apiAccess` | Internal API server -- enable, disable, rotate tokens |
+| `ws.logs` | Boot and command logs |
+| `ws.images` | Available workspace images |
+
+### CRUD
 
-const sandboxes = new OblienSandboxes(client);
+```typescript
+// Create
+const workspace = await ws.create({ image: 'node-20', mode: 'permanent' });
 
-// Create sandbox
-const sandbox = await sandboxes.create({
-    name: 'my-dev-env',
-    region: 'us-east-1',
-    template: 'node-20',
-    autoStart: true
-});
+// List
+const { workspaces } = await ws.list({ page: 1, limit: 20 });
 
-// Use sandbox
-const { url, token } = sandbox.sandbox;
-const response = await fetch(`${url}/files/list`, {
-    headers: { 'Authorization': `Bearer ${token}` }
-});
+// Get
+const data = await ws.get('ws_a1b2c3d4');
+
+// Update
+await ws.update('ws_a1b2c3d4', { name: 'production-api' });
 
-// Control lifecycle
-await sandboxes.stop(sandboxId);
-await sandboxes.start(sandboxId);
-await sandboxes.restart(sandboxId);
+// Delete
+await ws.delete('ws_a1b2c3d4');
+```
 
-// Regenerate token (1h expiry)
-const newToken = await sandboxes.regenerateToken(sandboxId);
+### Power controls
 
-// Get metrics
-const metrics = await sandboxes.getMetrics(sandboxId);
+```typescript
+await ws.start(id);
+await ws.stop(id);
+await ws.restart(id);
+await ws.pause(id);    // preserves memory state
+await ws.resume(id);
+await ws.ping(id);     // renews TTL for temporary workspaces
 ```
 
-**Features:**
-- ✅ Create, start, stop, restart, delete sandboxes
-- ✅ Auto-start option
-- ✅ Token management (1h JWT)
-- ✅ Resource metrics
-- ✅ Multiple templates & regions
-- ✅ Platform statistics
+### Account-level queries
 
-📖 [Full Documentation](./docs/SANDBOXES.md) | 💡 [Examples](./examples/sandbox-example.js)
+```typescript
+const quota = await ws.getQuota();
+const estimate = await ws.getEstimate({ cpu: 4, ram_mb: 8192 });
+```
 
 ---
 
-### 🗂️ Namespaces Module
+## Runtime (data plane)
 
-Manage namespaces and service configurations.
+The runtime connects to a running workspace and provides direct access to its filesystem, command execution, terminal sessions, search, and file watchers.
 
-```javascript
-import { OblienNamespaces } from 'oblien/namespaces';
+```typescript
+const rt = await ws.runtime('ws_a1b2c3d4');
+```
 
-const namespaces = new OblienNamespaces(client);
+This call enables the workspace's internal API server (if not already enabled), fetches a gateway JWT, and returns a `Runtime` instance. The token is cached -- subsequent calls for the same workspace return instantly.
 
-// Create namespace
-const namespace = await namespaces.create({
-    name: 'production',
-    slug: 'prod',
-    type: 'production'
-});
+### Files
 
-// Configure services
-await namespaces.configureService(namespaceId, {
-    service: 'ai',
-    enabled: true,
-    config: { /* ... */ }
-});
+```typescript
+// List directory
+const entries = await rt.files.list({ dirPath: '/app' });
 
-// Get usage stats
-const usage = await namespaces.getUsage(namespaceId);
-```
+// Read file
+const { content } = await rt.files.read({ filePath: '/app/index.js' });
 
-**Features:**
-- ✅ Namespace CRUD
-- ✅ Service configuration
-- ✅ Usage tracking
-- ✅ Activity logs
+// Write file
+await rt.files.write({ fullPath: '/app/config.json', content: '{}' });
 
-📖 [Documentation](./docs/NAMESPACES.md)
+// Create directory
+await rt.files.mkdir({ path: '/app/logs' });
 
----
+// Stat
+const stat = await rt.files.stat({ path: '/app/index.js' });
+
+// Delete
+await rt.files.delete({ path: '/app/tmp' });
 
-### 🎨 Icons Module
+// Stream directory tree (async generator)
+for await (const entry of rt.files.stream({ dirPath: '/app' })) {
+  console.log(entry.path);
+}
+```
 
-Search and fetch icons, images, and videos using AI-powered semantic search.
+### Exec
 
-```javascript
-import { OblienIcons } from 'oblien/icons';
+```typescript
+// Run a command and wait for result
+const result = await rt.exec.run(['npm', 'test']);
+console.log(result.exitCode, result.stdout, result.stderr);
 
-const icons = new OblienIcons(client);
+// Stream output as it happens (async generator)
+for await (const event of rt.exec.stream(['npm', 'run', 'build'])) {
+  process.stdout.write(event.data);
+}
 
-// Search for icons
-const results = await icons.search('home', { limit: 20 });
+// List running tasks
+const tasks = await rt.exec.list();
 
-// Fetch specific icons
-const icon = await icons.fetchIcon('settings gear');
+// Kill a task
+await rt.exec.kill(taskId);
 
-// Fetch multiple icons at once
-const iconSet = await icons.fetchIcons([
-    'home',
-    'user profile',
-    'settings',
-    'notification bell'
-]);
+// Send stdin to a running task
+await rt.exec.input(taskId, 'yes\n');
 
-// Fetch mixed media (icons, images, videos)
-const media = await icons.fetch([
-    { type: 'icon', description: 'user avatar' },
-    { type: 'image', description: 'mountain landscape' },
-    { type: 'video', description: 'product demo' }
-]);
+// Subscribe to a running task's output
+for await (const event of rt.exec.subscribe(taskId)) {
+  console.log(event);
+}
 ```
 
-**Features:**
-- ✅ Semantic icon search with AI embeddings
-- ✅ Fetch icons, images, and videos
-- ✅ Relevance scoring
-- ✅ Multiple icon styles (Outline, Filled, etc.)
-- ✅ Batch fetching
-- ✅ Pagination support
-- ✅ CDN-hosted assets
+### Terminal
 
-📖 [Full Documentation](./docs/ICONS.md) | 💡 [Examples](./examples/icons-example.js)
+```typescript
+// Create a terminal session
+const session = await rt.terminal.create({ shell: '/bin/bash' });
 
----
+// List sessions
+const sessions = await rt.terminal.list();
 
-### 💳 Credits Module
+// Get scrollback buffer
+const { data } = await rt.terminal.scrollback(session.id, { bytes: 4096 });
 
-Manage billing and credits.
+// Close session
+await rt.terminal.close(session.id);
+```
 
-```javascript
-import { OblienCredits } from 'oblien/credits';
+### Search
 
-const credits = new OblienCredits(client);
+```typescript
+// Search file contents (ripgrep)
+const hits = await rt.search.content({ query: 'TODO', path: '/app' });
 
-// Get balance
-const balance = await credits.getBalance();
+// Search file names
+const files = await rt.search.files({ query: 'config', path: '/app' });
 
-// Get usage
-const usage = await credits.getUsage({ period: 'monthly' });
+// Index status and initialization
+const status = await rt.search.status();
+await rt.search.init();
 ```
 
-**Features:**
-- ✅ Balance checking
-- ✅ Usage tracking
-- ✅ Transaction history
+### Watcher
+
+```typescript
+// Watch a directory for changes
+const watcher = await rt.watcher.create({ path: '/app/src' });
+
+// List active watchers
+const watchers = await rt.watcher.list();
+
+// Get watcher info
+const info = await rt.watcher.get(watcher.id);
+
+// Stop watching
+await rt.watcher.delete(watcher.id);
+```
 
 ---
 
-## Complete Example
+## WebSocket
 
-```javascript
-// Import client and modules
-import { OblienClient } from 'oblien';
-import { OblienAgents } from 'oblien/agents';
-import { OblienChat } from 'oblien/chat';
-import { OblienSandboxes } from 'oblien/sandbox';
+For real-time terminal I/O and file watcher events, open a persistent WebSocket connection:
 
-// Initialize
-const client = new OblienClient({
-    clientId: 'your-client-id',
-    clientSecret: 'your-client-secret'
+```typescript
+const socket = rt.ws();
+
+socket.onOpen(() => {
+  console.log('connected');
 });
 
-const agents = new OblienAgents(client);
-const chat = new OblienChat(client);
-const sandboxes = new OblienSandboxes(client);
-
-async function main() {
-    // 1. Create agent with tools
-    const agent = await agents.create({
-        name: 'Code Assistant',
-        namespace: 'production',
-        prompts: {
-            identity: 'You are a coding assistant.'
-        }
-    });
-
-    // Configure agent
-    const agentInstance = agents.agent(agent.agentId);
-    await agentInstance.settings.updateTools(['web-search', 'calculator']);
-    await agentInstance.settings.updateModelConfig({
-        temperature: 0.7,
-        max_tokens: 3000
-    });
-
-    // 2. Create sandbox for code execution
-    const sandbox = await sandboxes.create({
-        name: 'code-env',
-        template: 'node-20',
-        autoStart: true
-    });
-
-    // 3. Create chat session
-    const session = await chat.createSession({
-        agentId: agent.agentId,
-        namespace: 'production'
-    });
-
-    console.log('Setup complete!');
-    console.log('- Agent ID:', agent.agentId);
-    console.log('- Sandbox URL:', sandbox.sandbox.url);
-    console.log('- Session ID:', session.sessionId);
-}
+socket.onTerminalOutput((data) => {
+  process.stdout.write(data.output);
+});
 
-main();
+socket.onWatcherEvent((event) => {
+  console.log(event.type, event.path);
+});
+
+socket.onClose(() => {
+  console.log('disconnected');
+});
+
+socket.onError((err) => {
+  console.error(err);
+});
+
+await socket.connect();
+
+// Send input to a terminal
+socket.writeTerminalInput(sessionId, 'ls -la\n');
+
+// Resize terminal
+socket.resizeTerminal(sessionId, { cols: 120, rows: 40 });
 ```
 
 ---
 
-## Module Structure
+## SSE streaming
 
-```
-oblien/
-├── src/
-│   ├── agents/          # Agents management
-│   │   ├── index.js     # OblienAgents class
-│   │   ├── agent.js     # Agent instance
-│   │   ├── settings.js  # AgentSettings class
-│   │   └── tools.js     # Tools class
-│   ├── chat/            # Chat sessions
-│   │   ├── index.js     # OblienChat class
-│   │   └── session.js   # ChatSession class
-│   ├── sandbox/         # Sandboxes management
-│   │   ├── index.js     # OblienSandboxes class
-│   │   └── sandbox.js   # Sandbox instance
-│   ├── namespaces/      # Namespaces management
-│   ├── credits/         # Credits & billing
-│   └── client.js        # OblienClient (base)
-├── docs/                # Documentation
-│   ├── AGENTS_COMPLETE.md
-│   ├── SANDBOXES.md
-│   ├── CHAT.md
-│   └── NAMESPACES.md
-└── examples/            # Usage examples
-    ├── agents-complete-example.js
-    ├── sandbox-example.js
-    └── chat-example.js
+Several endpoints return server-sent events as async generators. Consume them with `for await`:
+
+```typescript
+// Stream workspace logs
+for await (const line of ws.logs.streamBoot(id)) {
+  console.log(line);
+}
+
+// Stream workload output
+for await (const event of ws.workloads.logsStream(id, workloadId)) {
+  process.stdout.write(event.data);
+}
+
+// Stream live metrics
+for await (const snapshot of ws.metrics.statsStream(id)) {
+  console.log(snapshot.cpu_percent, snapshot.memory_used_mb);
+}
+
+// Stream workload stats
+for await (const stats of ws.workloads.statsStream(id, workloadId)) {
+  console.log(stats);
+}
 ```
 
 ---
 
-## API Endpoints
+## Sub-resources
 
-| Module | Base Path | Operations |
-|--------|-----------|------------|
-| **Agents** | `/ai/agents` | CRUD, settings, tools, analytics |
-| **Chat** | `/ai/session` | Create, list, history |
-| **Sandboxes** | `/sandbox` | CRUD, start/stop/restart, metrics |
-| **Tools** | `/ai/tools` | List, search, create |
-| **Namespaces** | `/namespaces` | CRUD, services, usage |
+### Lifecycle
 
----
+```typescript
+const status = await ws.lifecycle.get(id);
 
-## Authentication
+// Convert to permanent
+await ws.lifecycle.makePermanent(id);
 
-All modules use client credentials authentication:
+// Convert to temporary with TTL
+await ws.lifecycle.makeTemporary(id, { ttl_seconds: 3600 });
 
-```javascript
-const client = new OblienClient({
-    clientId: 'your-client-id',        // X-Client-ID header
-    clientSecret: 'your-client-secret'  // X-Client-Secret header
+// Update TTL
+await ws.lifecycle.updateTtl(id, { ttl_seconds: 7200 });
+
+// Destroy (irreversible)
+await ws.lifecycle.destroy(id);
+```
+
+### Network
+
+```typescript
+const network = await ws.network.get(id);
+
+await ws.network.update(id, {
+  ingress: ['10.0.1.5'],
+  egress: ['10.0.1.10'],
+  allow_internet: false,
 });
+
+// Assign a dedicated outbound IP
+await ws.network.applyOutboundIp(id, { ip: '203.0.113.50' });
 ```
 
-Get your credentials from the [Oblien Dashboard](https://dashboard.oblien.com).
+### SSH
 
----
+```typescript
+await ws.ssh.enable(id, { password: 'secure-password' });
+await ws.ssh.enable(id, { publicKey: 'ssh-ed25519 AAAA...' });
+await ws.ssh.disable(id);
+const sshStatus = await ws.ssh.status(id);
+```
 
-## TypeScript Support
+### Public access
 
-The SDK includes TypeScript definitions:
+```typescript
+// Expose a port
+const endpoint = await ws.publicAccess.expose(id, {
+  port: 3000,
+  domain: 'app.yourdomain.com',
+});
+
+// List exposed ports
+const ports = await ws.publicAccess.list(id);
+
+// Revoke
+await ws.publicAccess.revoke(id, { port: 3000 });
+```
+
+### Snapshots
 
 ```typescript
-import { 
-    OblienClient, 
-    OblienAgents, 
-    Agent,
-    AgentSettings,
-    Tools,
-    OblienSandboxes,
-    Sandbox
-} from 'oblien';
+// Create a snapshot
+await ws.snapshots.create(id, { label: 'before-deploy' });
+
+// Restore
+await ws.snapshots.restore(id);
+
+// Archives
+await ws.snapshots.createArchive(id, { label: 'v1.0' });
+const archives = await ws.snapshots.listArchives(id);
+const archive = await ws.snapshots.getArchive(id, 'v1');
+await ws.snapshots.deleteArchive(id, 'v1');
+await ws.snapshots.deleteAllArchives(id);
+```
 
-const client: OblienClient = new OblienClient({
-    clientId: string,
-    clientSecret: string
+### Workloads
+
+```typescript
+// Create a managed workload
+await ws.workloads.create(id, {
+  name: 'server',
+  cmd: ['node', 'server.js'],
+  env: { PORT: '3000' },
 });
+
+const workloads = await ws.workloads.list(id);
+const workload = await ws.workloads.get(id, workloadId);
+await ws.workloads.start(id, workloadId);
+await ws.workloads.stop(id, workloadId);
+await ws.workloads.delete(id, workloadId);
+
+// Logs and stats (async generators)
+for await (const line of ws.workloads.logsStream(id, workloadId)) {
+  console.log(line);
+}
+for await (const snapshot of ws.workloads.statsStream(id, workloadId)) {
+  console.log(snapshot);
+}
 ```
 
----
+### Metrics
 
-## Error Handling
+```typescript
+const stats = await ws.metrics.stats(id);
+const info = await ws.metrics.info(id);
+const config = await ws.metrics.config(id);
 
-```javascript
-try {
-    const agent = await agents.create({ /* ... */ });
-} catch (error) {
-    console.error('Error:', error.message);
-    
-    if (error.message.includes('401')) {
-        // Authentication failed
-    } else if (error.message.includes('404')) {
-        // Resource not found
-    } else if (error.message.includes('429')) {
-        // Rate limit exceeded
-    }
+for await (const snapshot of ws.metrics.statsStream(id)) {
+  console.log(snapshot);
 }
 ```
 
----
+### Usage
 
-## Best Practices
+```typescript
+const usage = await ws.usage.get(id);
+const totals = await ws.usage.totals(id);
+const chart = await ws.usage.creditsChart(id);
+const global = await ws.usage.global();
+const activity = await ws.usage.activity();
+await ws.usage.wipe(id);
+```
 
-1. **Reuse Client**: Create one client instance and share across modules
-2. **Error Handling**: Always wrap API calls in try-catch
-3. **Token Management**: For sandboxes, refresh tokens before 1h expiry
-4. **Resource Cleanup**: Stop/delete unused sandboxes and sessions
-5. **Namespace Organization**: Use namespaces to separate environments
-6. **Tool Validation**: Validate tools before assigning to agents
+### Metadata
 
----
+```typescript
+const meta = await ws.metadata.get(id);
+await ws.metadata.update(id, { key: 'env', value: 'production' });
+await ws.metadata.patch(id, { key: 'version', value: '2.1.0' });
+```
 
-## Examples
+### API access
 
-### Multi-Agent System
+```typescript
+const status = await ws.apiAccess.status(id);
+const access = await ws.apiAccess.enable(id);
+await ws.apiAccess.disable(id);
+await ws.apiAccess.rotateToken(id);
+const token = await ws.apiAccess.getToken(id);
+const raw = await ws.apiAccess.rawToken(id);
+```
 
-```javascript
-// Create specialized agents
-const coder = await agents.create({
-    name: 'Coder',
-    prompts: { identity: 'Expert coder' }
-});
+### Logs
 
-const reviewer = await agents.create({
-    name: 'Reviewer',
-    prompts: { identity: 'Code reviewer' }
-});
+```typescript
+const log = await ws.logs.get(id);
+await ws.logs.clear(id);
+const files = await ws.logs.listFiles(id);
+const file = await ws.logs.getFile(id, 'boot.log');
 
-// Configure each with specific tools
-await agents.agent(coder.agentId).settings.updateTools([
-    'web-search', 'code-interpreter'
-]);
+for await (const line of ws.logs.streamBoot(id)) {
+  console.log(line);
+}
+for await (const line of ws.logs.streamCmd(id)) {
+  console.log(line);
+}
+```
+
+### Images
 
-await agents.agent(reviewer.agentId).settings.updateTools([
-    'code-analyzer', 'security-scanner'
-]);
+```typescript
+const images = await ws.images.list();
+const image = await ws.images.get('node-20');
 ```
 
-### Guest Chat System
+---
+
+## Standalone imports
 
-```javascript
-// Create agent for customer support
-const supportAgent = await agents.create({
-    name: 'Support Bot',
-    namespace: 'production'
-});
+The SDK exports `Workspace` and `Runtime` as standalone classes for cases where you need direct access without going through the main client:
+
+```typescript
+// Workspace (control plane) -- standalone
+import { Workspace } from 'oblien/workspace';
+
+const ws = new Workspace(client);
+await ws.create({ image: 'python-3.12' });
 
-// Set guest limits
-await agents.agent(supportAgent.agentId).settings.updateGuestLimits({
-    enabled: true,
-    max_messages_per_day: 100,
-    max_total_tokens_per_day: 50000
+// Runtime (data plane) -- standalone with a raw token
+import { Runtime } from 'oblien/runtime';
+
+const rt = new Runtime({
+  token: 'your_gateway_jwt',
 });
+await rt.files.list({ dirPath: '/' });
 
-// Create guest session
-const session = await chat.createGuestSession({
-    ip: req.ip,
-    fingerprint: req.headers['x-fingerprint'],
-    agentId: supportAgent.agentId
+// Runtime with a direct IP (bypass edge proxy)
+const directRt = new Runtime({
+  token: 'raw_token',
+  baseUrl: 'http://10.0.1.5:9990',
 });
 ```
 
 ---
 
-## Links
+## Error handling
+
+Every API error is an instance of `OblienError` with typed subclasses:
+
+```typescript
+import Oblien, {
+  OblienError,
+  AuthenticationError,
+  NotFoundError,
+  RateLimitError,
+  ValidationError,
+  PaymentRequiredError,
+  ConflictError,
+} from 'oblien';
+
+try {
+  await ws.get('ws_nonexistent');
+} catch (err) {
+  if (err instanceof NotFoundError) {
+    console.log('Workspace does not exist');
+  } else if (err instanceof AuthenticationError) {
+    console.log('Bad credentials');
+  } else if (err instanceof RateLimitError) {
+    console.log('Slow down -- retry after backoff');
+  } else if (err instanceof PaymentRequiredError) {
+    console.log('Quota exceeded -- upgrade your plan');
+  } else if (err instanceof ValidationError) {
+    console.log('Invalid parameters:', err.message);
+  } else if (err instanceof ConflictError) {
+    console.log('Workspace is in the wrong state for this operation');
+  } else if (err instanceof OblienError) {
+    console.log(`API error ${err.status}: ${err.message}`);
+  }
+}
+```
 
-- **Website**: https://oblien.com
-- **Documentation**: https://docs.oblien.com
-- **Dashboard**: https://dashboard.oblien.com
-- **API Reference**: https://api.oblien.com/docs
-- **Support**: support@oblien.com
-- **GitHub**: https://github.com/oblien/oblien
+| Error class | HTTP status | When |
+|-------------|-------------|------|
+| `AuthenticationError` | 401 | Invalid or missing credentials |
+| `PaymentRequiredError` | 402 | Credit quota exceeded |
+| `NotFoundError` | 404 | Resource does not exist |
+| `ConflictError` | 409 | Resource in wrong state for the operation |
+| `ValidationError` | 422 | Invalid request parameters |
+| `RateLimitError` | 429 | Too many requests |
 
 ---
 
-## License
+## Configuration
+
+```typescript
+const client = new Oblien({
+  clientId: 'your_client_id',       // required
+  clientSecret: 'your_client_secret', // required
+  baseUrl: 'https://api.oblien.com',  // optional, default
+});
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `clientId` | `string` | -- | Your API client ID |
+| `clientSecret` | `string` | -- | Your API client secret |
+| `baseUrl` | `string` | `https://api.oblien.com` | Control plane API base URL |
 
-MIT License - see LICENSE file for details
+Get your API keys from the [dashboard](https://oblien.com/dashboard).
 
 ---
 
-## Changelog
+## TypeScript
 
-### v1.3.0 (Latest)
-- ✅ Added `send()` method to Chat module with streaming support
-- ✅ Added `upload()` method for file attachments
-- ✅ Added guest usage monitoring (`getGuestUsage()`)
-- ✅ Added cache statistics (`getCacheStatistics()`)
-- ✅ Hybrid mode support (token or client credentials)
-- ✅ Complete Chat documentation with examples
+The SDK is written in TypeScript and ships its own type declarations. All request parameters, response shapes, and event types are fully typed and exported from the top-level package:
 
-### v1.2.0
-- ✅ Added Sandboxes module
-- ✅ Enhanced Agents module with proper settings sections
-- ✅ Added Tools management
-- ✅ Improved documentation
+```typescript
+import type {
+  WorkspaceCreateParams,
+  WorkspaceData,
+  ExecTask,
+  ExecStreamEvent,
+  FileEntry,
+  WSTerminalEvent,
+  WSWatcherEvent,
+} from 'oblien';
+```
 
-### v1.1.0
-- ✅ Added Agents module
-- ✅ Added Namespaces module
-- ✅ Guest session support
+---
+
+## Requirements
 
-### v1.0.0
-- ✅ Initial release
-- ✅ Chat module
-- ✅ Credits module
+- Node.js 18+
+- TypeScript 5.0+ (if using TypeScript)
+- ESM (`"type": "module"` in your package.json, or use dynamic `import()`)
 
 ---
 
-Made with ❤️ by the Oblien Team
+## Links
+
+- [Documentation](https://oblien.com/docs)
+- [SDK setup guide](https://oblien.com/docs/workspace/sdk-setup)
+- [Quickstart](https://oblien.com/docs/workspace/quickstart)
+- [API reference](https://oblien.com/docs/api)
+- [Runtime / Internal API](https://oblien.com/docs/internal-api)
+- [Dashboard](https://oblien.com/dashboard)
+- [GitHub](https://github.com/oblien/sdk)
+
+---
+
+## License
+
+MIT