Services and Preview URLs

A service is a long-running process inside a session - a web server, database, or any daemon. Start it with the services endpoint, optionally wait for its port to be ready, then access it via the session's public URL.

Start a service

POST to /services with the command to run. If you set waitForPort: true, the call blocks until the port is reachable or timeoutMs elapses. The service continues running after the call returns.

curl

curl -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/services \
  -H "x-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web",
    "cmd": "node",
    "args": ["server.js"],
    "cwd": "/workspace",
    "port": 3000,
    "waitForPort": true,
    "timeoutMs": 15000,
    "env": {
      "PORT": "3000"
    }
  }'
curl -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/services \
  -H "x-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web",
    "cmd": "node",
    "args": ["server.js"],
    "cwd": "/workspace",
    "port": 3000,
    "waitForPort": true,
    "timeoutMs": 15000,
    "env": {
      "PORT": "3000"
    }
  }'

Warning

Wait at least 10 seconds after starting a service before requesting its preview URL. The process needs time to start and bind the port, and the routing layer needs time to propagate the new port. A 502 immediately after starting a service is normal; retry with a brief pause.

Expose a port

To make a port reachable from the internet, call the expose endpoint. The session's publicUrl field is set to a stable HTTPS URL once a port is exposed.

curl

curl -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/expose \
  -H "x-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 3000, "access": "public"}'
curl -X POST \
  https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/expose \
  -H "x-api-key: API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 3000, "access": "public"}'

The access field controls who can reach the URL:

access	Behavior
`public`	Anyone with the URL can access it. Default.
`token-gated`	Requests must include the session token. Used for private previews.

List services

curl

curl https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/services \
  -H "x-api-key: API_KEY"
curl https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/services \
  -H "x-api-key: API_KEY"

Stop a service

curl

curl -X DELETE \
  https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/services/web \
  -H "x-api-key: API_KEY"
curl -X DELETE \
  https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/services/web \
  -H "x-api-key: API_KEY"

Service logs

Get the last N lines (up to 5000) as a snapshot:

curl

curl "https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/services/web/logs?lines=100" \
  -H "x-api-key: API_KEY"
curl "https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/services/web/logs?lines=100" \
  -H "x-api-key: API_KEY"

Or stream live output as SSE:

curl - SSE

curl -N "https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/services/web/logs/stream" \
  -H "x-api-key: API_KEY"
curl -N "https://api.mudbase.dev/api/sandboxes/projects/PROJECT_ID/sessions/SESSION_ID/services/web/logs/stream" \
  -H "x-api-key: API_KEY"

Note

The SSE log stream holds an open server connection. A per-org concurrent stream cap of 10 applies. Streams that are no longer needed should be closed to free the capacity.