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.

​
What the server provides

  • authenticated execution APIs (/execute, /execute/stream)
  • 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

  • GET /health is public
  • all other routes require Authorization: Bearer <api-key>
  • missing header -> 401
  • invalid token -> 403

​
Execution architecture

​
Request envelope

POST /execute and POST /execute/stream 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.