Workspace Internal API

The Workspace Internal API is the HTTP server running inside each workspace on port 9990. It exposes file operations, search, terminal sessions, and command execution - everything needed to interact with a workspace's runtime programmatically.

This is the same API regardless of how you reach it:

• Via the gateway at workspace.oblien.com - authenticates your JWT and routes to the Workspace
• Via private IP (10.x.x.x:9990) - workspace-to-workspace calls over the internal network

Architecture

┌─────────────────────────────────────────────────────────┐
│  Gateway access                                         │
│                                                         │
│  Your App ──► workspace.oblien.com ──► Workspace:9990   │
│               (gateway, JWT auth)      (internal API)   │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  Direct access (workspace-to-workspace)                 │
│                                                         │
│  Workspace A ──► 10.x.x.x:9990 ──► Workspace B         │
│                  (private IP, raw token)                 │
└─────────────────────────────────────────────────────────┘

Both paths hit the same HTTP server with the same endpoints. The only difference is authentication:

How it works - end to end

Gateway access

1. Enable public_access on the target workspace via the Network API - this allows the gateway to reach the Workspace through the firewall
2. Enable the server on the target workspace via the Oblien API - this starts port 9990 inside the Workspace and returns a signed Gateway JWT
3. The JWT embeds the Workspace's private IP, port, and workspace ID - you never need to know the IP yourself
4. Make requests to workspace.oblien.com with Authorization: Bearer <jwt> - the gateway unpacks the JWT and routes to the Workspace
5. The Internal API handles your request and returns the response

Direct access (workspace-to-workspace)

1. Enable the server on the target workspace
2. Add a private link from the calling workspace to the target via the Network API - this whitelists the caller's IP in the target's firewall
3. Get the raw connection token and private IP of the target workspace
4. Call http://10.x.x.x:9990/endpoint with Authorization: Bearer <raw_token> directly from the calling workspace
5. No gateway involved - direct Workspace-to-Workspace over the internal network

Quick start

import { OblienClient } from 'oblien';
import { Workspace } from 'oblien/workspace';

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

// 1. Enable the internal API server
const access = await ws.apiAccess.enable('ws_a1b2c3d4');

// 2. Use the workspace runtime APIs
const files = await ws.files.list('ws_a1b2c3d4', { dirPath: '/app' });
const content = await ws.files.get('ws_a1b2c3d4', { filePath: '/app/index.js' });
await ws.terminal.create('ws_a1b2c3d4', { shell: '/bin/bash' });

const result = await ws.exec.run('ws_a1b2c3d4', {
  cmd: ['node', '-e', 'console.log("hello")'],
});

Endpoint map

Files

Search

Terminal

Exec

File Watcher

WebSocket

Health

Oblien API vs Internal API

Next steps

• Connection & Auth - Enable the server, get tokens, set up access
• Files - List, read, write, stream files
• Search - Content and filename search
• Terminal - Interactive shell sessions
• Exec - Run commands
• File Watcher - Watch for file changes in real time
• Workspace Networking - Workspace-to-Workspace communication patterns and security model