oblien-runtime

# 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 **Internal 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 Internal API. Your application can use any other port.

---

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

# Connection & Authentication

Before using the [Workspace Internal API](/docs/internal-api), the HTTP server inside the VM must be enabled. Once enabled, there are **two ways** to connect:

| Method | URL | Auth | Network requirement | Use c...