---
name: oblien-runtime
description: >-
  Complete Oblien workspace environment - what you are running inside (Firecracker microVM), how auth works (gateway JWT vs raw token), and the full Runtime API reference: files, search, exec, terminal, and watcher on port 9990.
license: MIT
compatibility:
  - claude-code
  - cursor
  - openclaw
  - goose
  - jetbrains-ai
metadata:
  author: oblien
  version: 1.0.0
  source: https://oblien.com/docs
---

# Oblien Workspace Runtime

You are operating inside an **Oblien workspace** - an isolated Firecracker microVM with its own Linux kernel, filesystem, and network interface. This is not a container. You have full root access to a real Linux environment.

## What you can do

The workspace runs an **Runtime API** - an HTTP server on port 9990 inside the VM. Through this API you can:

- **Read and write files** anywhere on the filesystem
- **Execute commands** synchronously or stream output in real-time via SSE
- **Search code** using ripgrep (content search) or filesystem search (filename matching)
- **Open interactive terminal sessions** over WebSocket (multiplexed PTY)
- **Watch for file changes** in real-time over WebSocket

## How authentication works

There are two ways to reach this API:

| Method | URL | Token | When to use |
|--------|-----|-------|-------------|
| **Gateway** | `https://workspace.oblien.com` | Gateway JWT (~1hr, signed) | Calling from outside - your app, CI, SDK |
| **Direct** | `http://10.x.x.x:9990` | Raw connection token (hex) | Calling from another workspace (lower latency) |

Gateway access requires `public_access: true` on the workspace network config. Direct access requires a private link between the two workspaces.

## Key facts

- The filesystem persists across restarts (writable overlay on top of the base image)
- Default working directory is `/root`
- Outbound internet is ON by default, inbound is OFF by default (network-dark)
- The workspace has dedicated CPU, memory, and disk - configured at creation time
- Port 9990 is the Runtime API. Your application can use any other port.

---

The reference below covers every Runtime API endpoint with parameters, response schemas, and code examples.

## Reference files

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

- **[Connection & Authentication](references/server-setup.md)** (222 lines)
- **[Files](references/files.md)** (644 lines)
- **[Search](references/search.md)** (294 lines)
- **[Command Execution](references/exec.md)** (449 lines)
- **[Terminal Sessions](references/terminal.md)** (353 lines)
- **[File Watcher](references/watcher.md)** (329 lines)

### Quick search

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

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