Skip to main content
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 install @isol8/core

​
DockerIsol8

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.
​
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.
​
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

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

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.
Yes. start() initializes the engine or verifies remote health; stop() ensures cleanup (and session deletion for remote clients with 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.

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.