Skip to main content
The isol8 server exposes remote code execution over HTTP for centralized infrastructure.

​
Start server

isol8 serve --port 3000 --key "$ISOL8_API_KEY"
Port resolution order is --port > ISOL8_PORT > PORT > 3000. If the selected port is already in use, startup prompts for a different port or can auto-select one. Pass --auth-db to enable DB-backed API key management. Without a value, it defaults to a SQLite database at ~/.isol8/auth.db. You can also pass a connection string — the backend is auto-detected:
  • No value or file path (e.g. ./isol8-auth.db) → SQLite
  • postgres:// or postgresql:// → PostgreSQL
  • mysql:// → MySQL
When enabled, the --key value becomes the master key with admin privileges, and additional keys can be managed via the /auth/* endpoints. See Server routes for full endpoint reference.

​
What the server provides

  • authenticated execution APIs (/execute, /execute/stream, /execute/ws)
  • WebSocket streaming with automatic SSE fallback in RemoteIsol8
  • optional persistent sessions via sessionId
  • file upload/download for active sessions
  • global concurrency control via semaphore (maxConcurrent)
  • idle session cleanup (cleanup.autoPrune + cleanup.maxContainerAgeMs)
  • graceful shutdown cleanup (sessions, containers, and images)

​
Authentication model

isol8 supports two authentication modes that can work together:

​
Static key (default)

Pass a single API key via --key. This key acts as the master key with full access to all endpoints including key management.
  • GET /health is public
  • all other routes require Authorization: Bearer <api-key>
  • missing header -> 401
  • invalid token -> 403

​
DB-backed keys (optional)

Enable with --auth-db <connection> to store API keys in a database. Supported backends: SQLite (file path), PostgreSQL (postgres://), and MySQL (mysql://). When enabled:
  • The --key value becomes the master key with admin privileges
  • Additional keys are created via POST /auth/keys (master key required)
  • DB keys authenticate execution, file, and session endpoints
  • DB keys cannot access admin endpoints (/auth/*) — only the master key can
  • Keys have configurable TTL, tenant scoping, and can be revoked individually
  • POST /auth/login exchanges the master key for a short-lived token
Authentication order per request:
  1. Check static master key — sets authType = "master"
  2. Check DB key (if enabled) — sets authType = "apikey" and tenantId
  3. Reject with 401 (missing header) or 403 (invalid token)

​
Execution architecture

​
Request envelope

POST /execute, POST /execute/stream, and GET /execute/ws accept: 
{
  "request": {
    "code": "print('ok')",
    "runtime": "python"
  },
  "options": {
    "timeoutMs": 30000,
    "network": "none"
  },
  "sessionId": "optional-session-id"
}

​
Behavior rules

  • no sessionId: ephemeral execution (fresh engine lifecycle)
  • with sessionId: server creates/reuses persistent session
  • request options merge over server config defaults
  • poolStrategy and poolSize are always taken from server config
  • audit settings are applied from server config

​
Pool defaults (isol8 serve)

Server-created engines use config-level pool defaults:
  • poolStrategy (default: fast)
  • poolSize (default: { "clean": 1, "dirty": 1 })
{
  "poolStrategy": "fast",
  "poolSize": { "clean": 2, "dirty": 2 }
}
API requests cannot override pooling per call. Set pooling once in isol8.config.json for consistent server behavior.

​
Auto-pruning and idle session cleanup

When cleanup.autoPrune is enabled:
  • cleanup sweep runs every 60_000 ms
  • sessions idle longer than cleanup.maxContainerAgeMs are stopped and removed
  • active sessions are skipped while currently executing
  • lastAccessedAt is updated on execute and file upload/download calls
Default values:
  • cleanup.autoPrune: true
  • cleanup.maxContainerAgeMs: 3_600_000 (1 hour)
{
  "cleanup": {
    "autoPrune": true,
    "maxContainerAgeMs": 1800000
  }
}
Graceful shutdown (SIGINT/SIGTERM) runs cleanup for sessions, containers, and images. Abrupt termination (for example SIGKILL) skips graceful handlers; in that case, run isol8 cleanup.

Server routes

Full endpoint-by-endpoint request and response reference.

Remote server and client

Practical remote usage patterns with CLI, API, and library examples.

Configuration reference

Defaults and cleanup settings that affect server behavior.

Performance tuning

Pool strategy, pool size, and concurrency tuning guidance.

Troubleshooting

Diagnose auth, session, and remote execution issues.