Remote server and client

​

Diagram 1: Remote architecture overview

​

Start the server

isol8 serve \
  --key my-secret-key \
  --port 3000

export ISOL8_API_KEY=my-secret-key
isol8 serve --port 3000

​

Serve runtime behavior

• Bun/dev path: runs server in-process.
• Built CLI (Node) path: downloads/runs standalone isol8-server binary and can prompt for version update.
• Both paths run graceful cleanup on SIGINT/SIGTERM (sessions, containers, and images).

​

Authentication contract

• GET /health: no auth required.
• all other endpoints: require Authorization: Bearer <api-key>.

​

Where remote values are set

​

Request envelope

{
  "request": { "code": "print('ok')", "runtime": "python" },
  "options": { "timeoutMs": 30000 },
  "sessionId": "optional-session-id"
}

​

Execute remotely

curl -sS -X POST http://localhost:3000/execute \
  -H "Authorization: Bearer $ISOL8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request": {
      "code": "print(2 ** 10)",
      "runtime": "python"
    }
  }'

import { RemoteIsol8 } from "@isol8/core";

const engine = new RemoteIsol8(
  {
    host: "http://localhost:3000",
    apiKey: process.env.ISOL8_API_KEY!,
  },
  {
    timeoutMs: 30000,
    network: "none",
  }
);

await engine.start();
const result = await engine.execute({
  code: "print(2 ** 10)",
  runtime: "python",
});
await engine.stop();
console.log(result.stdout);

isol8 run -e "print(2 ** 10)" \
  --runtime python \
  --host http://localhost:3000 \
  --key "$ISOL8_API_KEY"

​

Persistent sessions

curl -sS -X POST http://localhost:3000/execute \
  -H "Authorization: Bearer $ISOL8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session-123",
    "request": { "code": "x = 41", "runtime": "python" }
  }'

const engine = new RemoteIsol8(
  {
    host: "http://localhost:3000",
    apiKey: process.env.ISOL8_API_KEY!,
    sessionId: "session-123",
  }
);

await engine.execute({ runtime: "python", code: "x = 41" });
const result = await engine.execute({ runtime: "python", code: "print(x + 1)" });
console.log(result.stdout); // 42\n

isol8 run -e "x = 41" \
  --runtime python \
  --host http://localhost:3000 \
  --key "$ISOL8_API_KEY" \
  --persistent

curl -X DELETE http://localhost:3000/session/session-123 \
  -H "Authorization: Bearer $ISOL8_API_KEY"

​

Auto-pruning setup (idle session cleanup)

• sweep interval: every 60_000 ms (60s)
• idle threshold: cleanup.maxContainerAgeMs
• active sessions are skipped while executing (isActive === true)
• lastAccessedAt is refreshed on execute and file upload/download calls

​

Defaults

• cleanup.autoPrune: true
• cleanup.maxContainerAgeMs: 3_600_000 (1 hour)

​

Configure in isol8.config.json

{
  "cleanup": {
    "autoPrune": true,
    "maxContainerAgeMs": 1800000
  }
}

​

Practical tuning guidance

• shorter idle timeout (5m to 30m): lower container footprint, more frequent cold session starts
• longer idle timeout (1h to 24h): better session reuse, higher idle resource usage
• disable auto-prune only if you have explicit lifecycle management (for example always calling DELETE /session/:id)

​

Streaming behavior

• POST /execute/stream emits SSE events (stdout, stderr, exit, error).
• current server implementation always uses ephemeral mode for streaming path.

​

File APIs (persistent sessions only)

• POST /file: upload base64 content to session container
• GET /file?sessionId=...&path=...: download base64 content

curl -sS -X POST http://localhost:3000/file \
  -H "Authorization: Bearer $ISOL8_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "session-123",
    "path": "/sandbox/input.txt",
    "content": "aGVsbG8K"
  }'

await engine.putFile("/sandbox/input.txt", "hello\n");
const file = await engine.getFile("/sandbox/input.txt");
console.log(file.toString("utf-8")); // hello

​

Operations checklist

• keep strict defaults in isol8.config.json (network: "none" by default)
• size maxConcurrent to host capacity
• configure cleanup pruning for session-heavy workloads
• place TLS/rate limiting in front of the service
• enable audit logging when provenance/compliance is required

​

FAQ

​

Troubleshooting

• Server start fails with API key error: pass --key or set ISOL8_API_KEY.
• Session not found on file calls: create session first via /execute with the same sessionId.
• Session state unexpectedly gone: check prune settings in cleanup.autoPrune and cleanup.maxContainerAgeMs.
• Remote request hangs under load: inspect maxConcurrent queueing and host saturation.

​

Related pages