Connection & Auth

Before using the Workspace Runtime API, the HTTP server inside the VM must be enabled. Once enabled, there are two ways to connect:

Both methods hit the same server and the same endpoints. The difference is how you authenticate and how the request reaches the VM.

Enable the server

Start the internal server via the Oblien API. This returns a Gateway JWT for immediate use.

import Oblien from 'oblien';

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

const access = await client.workspaces.apiAccess.enable('ws_a1b2c3d4');
console.log(access.token);   // Gateway JWT (eyJhbG...)
console.log(access.enabled); // true

POST https://api.oblien.com/workspace/ws_a1b2c3d4/runtime-api-access/enable
X-Client-ID: your_client_id
X-Client-Secret: your_client_secret

curl -X POST "https://api.oblien.com/workspace/ws_a1b2c3d4/runtime-api-access/enable" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Gateway connection

Use the Gateway JWT to access the workspace through workspace.oblien.com. The JWT embeds the VM's private IP and port - the gateway decodes it and routes your request to the correct VM automatically.

await client.workspaces.network.update('ws_a1b2c3d4', { public_access: true });

// The SDK manages tokens automatically via client.workspaces.runtime()
const rt = await client.workspaces.runtime('ws_a1b2c3d4');

const files = await rt.files.list({ dirPath: '/app' });
const result = await rt.exec.run(['ls', '-la']);
await rt.terminal.create({ shell: '/bin/bash' });

GET https://workspace.oblien.com/files?path=/app
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# HTTP
curl "https://workspace.oblien.com/files?path=/app" \
  -H "Authorization: Bearer $GATEWAY_JWT"

# WebSocket
wscat -c "wss://workspace.oblien.com/ws" \
  -H "Authorization: Bearer $GATEWAY_JWT"

Token lifetime

The standard Gateway JWT expires after ~1 hour. You have two options to manage this:

• Rotate - call rotateToken or re-enable to get a fresh short-lived JWT
• Force refresh - use client.workspaces.runtime(id, { force: true }) in the SDK to bypass the cached token

Both token types work the same way - Authorization: Bearer <token> against workspace.oblien.com. The only difference is expiry.

Direct connection

For workspace-to-workspace communication, connect directly to the target VM's private IP. This bypasses the gateway entirely - lower latency, no JWT overhead.

Setup flow

1. Enable the server on the target workspace
2. Create a private link from caller → target
3. Get the raw token + private IP of the target
4. Call the target directly from the calling workspace

Step 1: Enable the target

await client.workspaces.apiAccess.enable('ws_target');

Step 2: Create a private link

Private links open a network path between two workspaces. Without a link, VMs cannot reach each other - they are network-dark by default. The link whitelists the caller's IP in the target workspace's firewall.

await client.workspaces.network.update('ws_target', {
  private_link_ids: ['ws_caller'],
});

Step 3: Get the raw connection token

The raw token is a hex string used directly by the VM's auth middleware. Unlike the Gateway JWT, it doesn't embed routing info - you provide the IP yourself.

const raw = await client.workspaces.apiAccess.rawToken('ws_target');

console.log(raw.token); // "a1b2c3d4e5f6..."
console.log(raw.ip);    // "10.0.1.42"
console.log(raw.port);  // 9990

See the full endpoint reference at Raw token.

Step 4: Call from the other workspace

From code running inside ws_caller, call ws_target directly over the private network:

// Running inside ws_caller
const res = await fetch('http://10.0.1.42:9990/files?path=/app', {
  headers: { 'Authorization': `Bearer ${raw.token}` },
});
const files = await res.json();

curl "http://10.0.1.42:9990/exec" \
  -H "Authorization: Bearer a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"cmd":["npm","test"]}'

Disable the server

Stop the internal server, kill all sessions, and close connections.

await client.workspaces.apiAccess.disable('ws_a1b2c3d4');

See the full endpoint reference at Disable server.

Token comparison

Full API access reference

All server management endpoints are on the Oblien API at api.oblien.com: