Skip to main content
isol8 exposes two main classes: DockerIsol8 for local execution and RemoteIsol8 for connecting to a remote isol8 server. Both implement the Isol8Engine interface.

​
Installation

npm install isol8

​
DockerIsol8

Executes code locally using Docker. This is the primary engine. 
import { DockerIsol8 } from "isol8";

const isol8 = new DockerIsol8({
  mode: "ephemeral",        // "ephemeral" | "persistent"
  network: "none",          // "none" | "host" | "filtered"
  memoryLimit: "512m",
  cpuLimit: 1.0,
  pidsLimit: 64,
  readonlyRootFs: true,
  maxOutputSize: 1048576,   // 1MB
  timeoutMs: 30000,
  sandboxSize: "64m",
  tmpSize: "64m",
  secrets: {},              // Secret env vars (values masked in output)
  persist: false,           // Keep container after execution for debugging
  debug: false,             // Enable internal debug logging
});

await isol8.start();  // No-op — containers are created lazily
// ... execute code ...
await isol8.stop();   // Kills container (persistent) or drains pool (ephemeral)

​
Constructor Options

All options are optional with sensible defaults.
​
mode
'ephemeral' | 'persistent'
default:"ephemeral"
Execution mode. Ephemeral uses the warm container pool. Persistent keeps a single container alive.
​
network
'none' | 'host' | 'filtered'
default:"none"
Container network mode.
​
networkFilter
object
Network filtering rules (only used when network is "filtered").
​
memoryLimit
string
default:"512m"
Docker memory limit string.
​
cpuLimit
number
default:"1.0"
CPU cores (fractional).
​
pidsLimit
number
default:"64"
Maximum number of processes.
​
readonlyRootFs
boolean
default:"true"
Mount root filesystem as read-only.
​
maxOutputSize
number
default:"1048576"
Maximum output size in bytes before truncation.
​
timeoutMs
number
default:"30000"
Default execution timeout in milliseconds.
​
sandboxSize
string
default:"64m"
Size of the /sandbox tmpfs mount.
​
tmpSize
string
default:"64m"
Size of the /tmp tmpfs mount.
​
image
string
Override Docker image. Ignores runtime adapter’s default image.
​
secrets
Record<string, string>
default:"{}"
Secret environment variables. Values are injected into the container and automatically masked in output.
​
persist
boolean
default:"false"
Keep the container running after execution completes instead of cleaning it up. Useful for debugging — inspect the container’s filesystem and state post-execution. This is different from mode: "persistent", which keeps a container alive between runs for stateful sessions.
​
debug
boolean
default:"false"
Enable debug logging for internal engine operations. When true, the engine prints detailed logs about container lifecycle, pool operations, and cleanup decisions with a [DEBUG] prefix. Does not affect the executed code’s output.

​
RemoteIsol8

Connects to a remote isol8 server via HTTP. 
import { RemoteIsol8 } from "isol8";

const isol8 = new RemoteIsol8(
  {
    host: "http://localhost:3000",
    apiKey: "my-secret-key",
    sessionId: "my-session",  // Optional: enables persistent mode
  },
  {
    network: "none",
    memoryLimit: "256m",
  }
);

await isol8.start();   // Verifies server health via GET /health
const result = await isol8.execute({ code: "print(1)", runtime: "python" });
await isol8.stop();    // Sends DELETE /session/:id if sessionId was set

​
Container Cleanup

The DockerIsol8 class provides a static utility method to remove all isol8 containers from your Docker environment. This is useful for maintenance, testing, and cleanup operations. 
import { DockerIsol8 } from "isol8";

// Remove all isol8 containers
const result = await DockerIsol8.cleanup();

console.log(`Removed: ${result.removed}`);
console.log(`Failed: ${result.failed}`);

if (result.errors.length > 0) {
  console.error("Errors:", result.errors);
}

​
Cleanup Result

The cleanup() method returns an object with:
​
removed
number
Number of containers successfully removed.
​
failed
number
Number of containers that failed to remove.
​
errors
string[]
Array of error messages for failed removals (format: "containerId: error message").

​
Custom Docker Instance

You can pass a custom Docker instance to the cleanup method: 
import Docker from "dockerode";
import { DockerIsol8 } from "isol8";

const docker = new Docker({ socketPath: "/custom/docker.sock" });
const result = await DockerIsol8.cleanup(docker);

​
Use Cases

Common scenarios for programmatic cleanup: 
// Clean up before test suite
beforeEach(async () => {
  await DockerIsol8.cleanup();
});

// Clean up after test suite
afterAll(async () => {
  const result = await DockerIsol8.cleanup();
  if (result.failed > 0) {
    console.warn(`Warning: ${result.failed} containers failed to clean up`);
  }
});

// Periodic maintenance in a long-running service
setInterval(async () => {
  const result = await DockerIsol8.cleanup();
  console.log(`Cleaned up ${result.removed} orphaned containers`);
}, 3600000); // Every hour
The cleanup() method only removes containers using isol8 images (isol8:* or isol8-custom:*). Your other Docker containers are never affected.

​
Isol8Engine Interface

Both DockerIsol8 and RemoteIsol8 implement this interface: 
interface Isol8Engine {
  start(): Promise<void>;
  stop(): Promise<void>;
  execute(req: ExecutionRequest): Promise<ExecutionResult>;
  executeStream(req: ExecutionRequest): AsyncIterable<StreamEvent>;
  putFile(path: string, content: Buffer | string): Promise<void>;
  getFile(path: string): Promise<Buffer>;
}