Runtime API

VM Runtime API

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

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

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

This is different from the Oblien API at api.oblien.com, which manages VM lifecycle (create, start, stop, delete). The Runtime API operates inside the running VM itself.

Architecture

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

Access methodAuthNetwork requirementHow you get it
Gateway (vm.oblien.com)Gateway JWT (Authorization: Bearer)public_access: true on the targetEnable server on the Oblien API
Direct (private IP)Raw connection token (Authorization: Bearer)Private link from caller to targetGet raw token on the Oblien API

How it works - end to end

Gateway access

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

Direct access (VM-to-VM)

  1. Enable the server on the target VM
  2. Add a private link from the calling VM 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 VM
  4. Call http://10.x.x.x:9990/endpoint with Authorization: Bearer <raw_token> directly from the calling VM
  5. No gateway involved - direct VM-to-VM over the internal network

VMs are network-dark by default. Every VM has a firewall that blocks all inbound traffic unless explicitly allowed. No VM can reach any other VM until you create a private link - even VMs in the same account are fully isolated.

Quick start

import Oblien from 'oblien';

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

// 1. Enable the Runtime API server
const access = await client.vms.apiAccess.enable('ws_a1b2c3d4');

// 2. Get a runtime connection (auto-fetches JWT)
const rt = await client.vms.runtime('ws_a1b2c3d4');

// 3. Use runtime APIs - no vm ID needed
const files = await rt.files.list({ dirPath: '/app' });
const content = await rt.files.read({ filePath: '/app/index.js' });
await rt.terminal.create({ shell: '/bin/bash' });

const result = await rt.exec.run(
  ['node', '-e', 'console.log("hello")'],
);

Endpoint map

Files

EndpointMethodDescription
/filesGETList directory
/files/listGETList directory (alias)
/files/streamGETStream directory as NDJSON
/files/readGETRead file content
/files/writePOST/PUTWrite file
/files/mkdirPOSTCreate directory
/files/statGETFile/directory info
/files/deleteDELETE/POSTDelete file or directory
/files/transfer/downloadPOSTStream a tar.gz archive from the VM
/files/transfer/uploadPOSTUpload and extract a tar.gz archive into the VM
EndpointMethodDescription
/files/searchGETContent search (ripgrep)
/files/search/filesGETFilename search
/files/search/initPOSTInstall ripgrep
/files/search/initGETCheck ripgrep status

Terminal

EndpointMethodDescription
/terminalsPOSTCreate terminal session
/terminalsGETList active sessions
/terminals/:idDELETEClose session
/terminals/:id/scrollbackGETGet scrollback buffer

Exec

EndpointMethodDescription
/execPOSTRun a command
/execGETList tasks
/exec/:idGETGet task status
/exec/:idDELETEKill a running task
/execDELETEDelete all tasks
/exec/:id/inputPOSTSend stdin input
/exec/streamGET/POSTStream task output (SSE)

File Watcher

EndpointMethodDescription
/watchersPOSTCreate a file watcher
/watchersGETList active watchers
/watchers/:idGETGet watcher info
/watchers/:idDELETEStop and remove a watcher

WebSocket

EndpointDescription
/wsMultiplexed WebSocket for terminal I/O and file watcher events

Proxy

EndpointMethodDescription
/proxyANYReverse-proxy HTTP/WebSocket to a loopback port inside the VM (target via X-Oblien-Proxy-Target header, x_oblien_target query, or /proxy/<port>/…)

Health

EndpointMethodDescription
/healthGETServer health check (no auth required)

Oblien API vs Runtime API

Oblien APIVM Runtime API
Base URLapi.oblien.comvm.oblien.com or 10.x.x.x:9990
AuthAPI Key (X-Client-ID + X-Client-Secret)Gateway JWT or raw connection token
PurposeVM lifecycle (create, start, stop)Runtime operations (files, exec, terminal)
Runs onOblien control planeInside each VM
ScopeAll your VMsSingle VM
File accessBase64 encoded via APIDirect filesystem (plaintext)
Search-Content + filename search
TerminalIndirect (via Oblien API)Direct PTY sessions
LatencyHigher (multiple hops)Lower (gateway → VM or VM → VM)

Next steps