Proxy

Reach an HTTP or WebSocket server running on a loopback port inside the workspace (for example a dev server on 127.0.0.1:3000) as if you were talking to it directly. Request and response headers, streaming/SSE bodies, and WebSocket upgrades all pass through near-natively.

Overview

1. A service listens on 127.0.0.1:<port> inside the workspace (e.g. a dev server)
2. Call /proxy with the target port    →  runtime forwards to 127.0.0.1:<port>
3. HTTP response / stream / WS frames   →  passed back through untouched

The runtime connection token is used to authenticate the request to /proxy and is stripped before the request reaches the in-VM app, so it never leaks to code running inside the workspace.

Target resolution

The target port is selected by the first of these that is present:

When the header or query form is used, the upstream path is the request path with the leading /proxy removed. The host, if given, must be a loopback address. token and x_oblien_target are reserved query params and are removed before forwarding upstream.

HTTP request

Forward an HTTP request to a loopback port. The SDK returns the raw Response so you get the upstream status, headers, and body (including streams).

const rt = await client.workspaces.runtime('ws_a1b2c3d4');

// GET → raw fetch Response
const res = await rt.proxy(3000).fetch('/api/users?limit=10');
const users = await res.json();

// POST with a body
await rt.proxy(3000).fetch('/api/users', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ name: 'ada' }),
});

GET https://workspace.oblien.com/proxy/api/users?limit=10
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
X-Oblien-Proxy-Target: 3000

GET https://workspace.oblien.com/proxy/3000/api/users?limit=10
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# Header form
curl "https://workspace.oblien.com/proxy/api/users?limit=10" \
  -H "Authorization: Bearer $GATEWAY_JWT" \
  -H "X-Oblien-Proxy-Target: 3000"

# Path form
curl "https://workspace.oblien.com/proxy/3000/api/users?limit=10" \
  -H "Authorization: Bearer $GATEWAY_JWT"

The response is returned verbatim — status code, headers, and body. Streaming responses (chunked, Server-Sent Events) are flushed through immediately.

Streaming (SSE)

const stream = await rt.proxy(8080).fetch('/events');
for await (const chunk of stream.body!) {
  process.stdout.write(new TextDecoder().decode(chunk));
}

WebSocket

Open a WebSocket to a loopback port. Auth and target are passed as query params (token, x_oblien_target) because the browser WebSocket API cannot set request headers.

const ws = rt.proxy(3000).ws('/socket');

ws.onmessage = (e) => console.log(e.data);
ws.onopen = () => ws.send('hello');

wss://workspace.oblien.com/proxy/socket?token=<GATEWAY_JWT>&x_oblien_target=3000

Error responses