> ## Documentation Index
> Fetch the complete documentation index at: https://isol8.notdhruv.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Server overview
> Run isol8 as an authenticated HTTP execution service with concurrency control, persistent sessions, file APIs, streaming, and auto-pruning.
The isol8 server exposes remote code execution over HTTP for centralized infrastructure.
## Start server
```bash theme={null}
isol8 serve --port 3000 --key "$ISOL8_API_KEY"
```
```bash theme={null}
# SQLite (default path ~/.isol8/auth.db)
isol8 serve --port 3000 --key "$ISOL8_API_KEY" --auth-db
# SQLite (custom path)
isol8 serve --port 3000 --key "$ISOL8_API_KEY" --auth-db ./isol8-auth.db
# PostgreSQL
isol8 serve --port 3000 --key "$ISOL8_API_KEY" --auth-db "postgres://user:pass@localhost:5432/isol8"
# MySQL
isol8 serve --port 3000 --key "$ISOL8_API_KEY" --auth-db "mysql://user:pass@localhost:3306/isol8"
```
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 `
* missing header -> `401`
* invalid token -> `403`
### DB-backed keys (optional)
Enable with `--auth-db ` 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
```mermaid theme={null}
flowchart TD
A["Client"] --> B["Hono server"]
B --> C["Auth middleware"]
C --> D["Global semaphore"]
D --> E["DockerIsol8 engine"]
E --> F["Sandbox container(s)"]
style A fill:#f9f,stroke:#333
A -- "HTTP" --> B
A -- "WebSocket" --> B
```
## Request envelope
`POST /execute`, `POST /execute/stream`, and `GET /execute/ws` accept:
```json theme={null}
{
"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 }`)
```json theme={null}
{
"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)
```json theme={null}
{
"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`.
## Related pages
Full endpoint-by-endpoint request and response reference.
Practical remote usage patterns with CLI, API, and library examples.
Defaults and cleanup settings that affect server behavior.
Pool strategy, pool size, and concurrency tuning guidance.
Diagnose auth, session, and remote execution issues.