Library reference

Detailed TypeScript API guide for DockerIsol8 and RemoteIsol8, with option-by-option descriptions and lifecycle behavior.

isol8 exposes two main classes:

• DockerIsol8 for local execution
• RemoteIsol8 for remote HTTP execution

Both implement Isol8Engine.

Use DockerIsol8 for local in-process execution. Use RemoteIsol8 when execution is handled by an isol8 serve instance over HTTP.

Installation

npm

npm install @isol8/core

DockerIsol8

Input

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

const isol8 = new DockerIsol8({
  mode: "ephemeral",
  network: "none",
  timeoutMs: 30000,
});

await isol8.start();
const result = await isol8.execute({ code: "print(1)", runtime: "python" });
await isol8.stop();

Constructor options (Isol8Options)

mode · 'ephemeral' | 'persistent' · default: "ephemeral"

Execution mode. Ephemeral uses warm pool containers. Persistent reuses one container.

network · 'none' | 'host' | 'filtered' · default: "none"

Network policy for execution container.

network: "host" gives untrusted code full network egress. Prefer none or filtered for most workloads.

networkFilter · { whitelist: string[]; blacklist: string[] }

Filter rules used only when network is "filtered".

cpuLimit · number · default: "1"

CPU limit as fraction/cores.

memoryLimit · string · default: "512m"

Memory cap for container.

pidsLimit · number · default: "64"

Maximum process count in container.

readonlyRootFs · boolean · default: "true"

Mount root filesystem read-only.

maxOutputSize · number · default: "1048576"

Output truncation threshold in bytes.

secrets · Record<string, string> · default: "{}"

Secret env variables; values are masked in stdout/stderr post-processing.

timeoutMs · number · default: "30000"

Default timeout applied when request timeout is omitted.

image · string

Override runtime image selection.

sandboxSize · string · default: "512m"

Size of /sandbox tmpfs mount.

tmpSize · string · default: "256m"

Size of /tmp tmpfs mount.

debug · boolean · default: "false"

Enable internal debug logs.

persist · boolean · default: "false"

Keep container running after execution completes (debug/inspection use case).

logNetwork · boolean · default: "false"

Include network request logs in result when filtered mode is used.

security · SecurityConfig

Seccomp behavior (strict, unconfined, custom).

audit · AuditConfig

Audit logging configuration.

poolStrategy · 'fast' | 'secure' · default: "fast"

Strategies for managing the ephemeral container pool.

• fast: Dual-pool system (clean/dirty) with background cleanup. Use for high-throughput.
• secure: Synchronous cleanup before every acquisition. Use for maximum isolation assurance.

poolSize · number | { clean: number; dirty: number } · default: "{ clean: 1, dirty: 1 }"

Warm pool size config.

RemoteIsol8

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

const isol8 = new RemoteIsol8(
  {
    host: "http://localhost:3000",
    apiKey: "my-secret-key",
    sessionId: "session-123", // optional
  },
  {
    network: "none",
    memoryLimit: "512m",
  }
);

RemoteIsol8.start() performs a /health check. RemoteIsol8.stop() deletes the remote session only when sessionId is set.

host · string · required

Base URL of remote server.

apiKey · string · required

Bearer token for authentication.

sessionId · string

Optional persistent session identifier.

options · Isol8Options

Engine options sent with remote execution requests.

Isol8Engine methods

start(options?) · Promise<void>

Initializes engine (or checks remote health). DockerIsol8 accepts optional startup prewarm settings, for example:

• start({ prewarm: true }) to prewarm all runtimes
• start({ prewarm: { runtimes: ["python", "node"] } }) to prewarm selected runtimes

stop() · Promise<void>

Stops local resources or deletes remote session if used.

execute(req) · Promise<ExecutionResult>

Runs code and returns full result.

executeStream(req) · AsyncIterable<StreamEvent>

Streams stdout, stderr, exit, and error events. For RemoteIsol8, automatically uses WebSocket transport with SSE fallback.

putFile(path, content) · Promise<void>

Upload file into active persistent/session container.

getFile(path) · Promise<Buffer>

Download file from active persistent/session container.

File methods require stateful execution context: local persistent mode or a remote client with sessionId.

ExecutionRequest fields

code · string · required

Source code to execute.

runtime · Runtime · required

Runtime selection.

timeoutMs · number

Per-request timeout override.

env · Record<string, string>

Extra environment variables.

fileExtension · string

Optional script extension override.

stdin · string

Stdin payload.

files · Record<string, string | Buffer>

Files to inject before execution.

outputPaths · string[]

Files to retrieve after execution.

installPackages · string[]

Runtime-specific packages to install pre-run.

setupScript · string

Inline shell script executed before the main code. Runs as the sandbox user from /sandbox. Useful for cloning repos, creating files, configuring tools, etc.

workdir · string · default: "/sandbox"

Working directory for the main code execution. Must resolve to a path inside /sandbox.

metadata · Record<string, string>

Metadata to attach to audit records.

ExecutionResult fields

stdout · string

Captured standard output.

stderr · string

Captured standard error.

exitCode · number

Process exit code.

durationMs · number

Wall time for execution.

truncated · boolean

Whether output exceeded maxOutputSize.

executionId · string

Unique execution identifier.

runtime · Runtime

Runtime used for this execution.

timestamp · string

ISO timestamp.

containerId · string

Container ID when available.

files · Record<string, string>

Base64 file map for requested outputPaths.

resourceUsage · object

CPU/memory/network usage metrics (when enabled).

networkLogs · NetworkLogEntry[]

Request logs in filtered mode (when enabled).

Cleanup helper

Input

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

const result = await DockerIsol8.cleanup();
console.log(result.removed, result.failed, result.errors);

const imageResult = await DockerIsol8.cleanupImages();
console.log(imageResult.removed, imageResult.failed, imageResult.errors);

removed · number

Number of containers removed.

failed · number

Number of removals that failed.

errors · string[]

Error list for failed removals.

FAQ

When should I switch from DockerIsol8 to RemoteIsol8?

Use DockerIsol8 for local workflows and single-node apps. Use RemoteIsol8 when execution is centralized behind isol8 serve, shared across services, or isolated from app hosts.

Do I always need to call start() and stop()?

Yes. start() initializes the engine or verifies remote health; stop() ensures cleanup (and session deletion for remote clients with sessionId).

Why do file operations fail in remote mode without sessionId?

putFile and getFile require a persistent remote session. Set sessionId when constructing RemoteIsol8.

Troubleshooting quick checks

• Remote server health check failed: verify host URL, server status, and API key.
• File operations require a sessionId: set sessionId for RemoteIsol8 before using putFile/getFile.
• No streamed events from executeStream: confirm server supports /execute/stream and the request is valid.
• Unexpected truncation: increase maxOutputSize in constructor options.

Related pages

Execution guide

Lifecycle, modes, streaming, and result semantics.

Option mapping

Map every library option to CLI, config, and API equivalents.

How to CLI

Command-line behavior and flag-by-flag details.

Troubleshooting

Diagnose runtime, network, and session issues quickly.