Skip to main content
isol8 supports file transfer in two ways:
  1. Per-request — Use files and outputPaths in ExecutionRequest (works in both ephemeral and persistent modes)
  2. Direct — Use putFile() and getFile() on the engine (persistent mode only)

​
Per-Request File I/O

The simplest approach. Works in both ephemeral and persistent modes.

​
Injecting Files

Pass files as part of the execution request: 
const result = await isol8.execute({
  code: `
with open("/sandbox/input.txt") as f:
    print(f.read().upper())
  `,
  runtime: "python",
  files: {
    "/sandbox/input.txt": "hello world",
    "/sandbox/config.json": JSON.stringify({ key: "value" }),
    "/sandbox/binary.dat": Buffer.from([0x00, 0x01, 0x02]),
  },
});
File values can be string or Buffer.

​
Retrieving Files

Specify paths to retrieve after execution: 
const result = await isol8.execute({
  code: `
with open("/sandbox/output.csv", "w") as f:
    f.write("name,score\\nAlice,95\\nBob,87")
  `,
  runtime: "python",
  outputPaths: ["/sandbox/output.csv"],
});

// Files are base64-encoded in the result
const csv = Buffer.from(result.files!["/sandbox/output.csv"], "base64").toString();
console.log(csv);

​
Direct File API (Persistent Mode)

In persistent mode, you can transfer files directly to/from the container at any time. 
const isol8 = new DockerIsol8({ mode: "persistent" });
await isol8.start();

// You must execute at least once to create the container
await isol8.execute({ code: "print('init')", runtime: "python" });

// Upload a file
await isol8.putFile("/sandbox/data.csv", "col1,col2\n1,2\n3,4");

// Execute code that uses the file
await isol8.execute({
  code: `
import csv
with open("/sandbox/data.csv") as f:
    for row in csv.reader(f):
        print(row)
  `,
  runtime: "python",
});

// Download a file
const content = await isol8.getFile("/sandbox/data.csv");
console.log(content.toString()); // "col1,col2\n1,2\n3,4"

await isol8.stop();
putFile() and getFile() throw an error if no container is active. They require persistent mode and at least one prior execution.

​
File Transfer via HTTP

The server exposes file upload/download endpoints for persistent sessions:

​
Upload

curl -X POST http://localhost:3000/file \
  -H "Authorization: Bearer my-key" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "my-session",
    "path": "/sandbox/data.csv",
    "content": "Y29sMSxjb2wyCjEsMgozLDQ="
  }'
The content field is base64-encoded.

​
Download

curl "http://localhost:3000/file?sessionId=my-session&path=/sandbox/data.csv" \
  -H "Authorization: Bearer my-key"
Returns { "content": "<base64-encoded>" }.

​
File Paths

All files should be placed under /sandbox/ — this is the writable tmpfs working directory inside the container. The root filesystem is read-only by default.
The /sandbox tmpfs defaults to 64MB. Use --sandbox-size 256m (CLI) or sandboxSize: "256m" (library) to increase it for data-intensive workloads.