LinkedInGitHub

Getting started

Install

npm install agentpad

Prerequisites: Node.js 18+. SQL support requires the sqlite3 CLI on $PATH.

Quick start

import { Runtime } from "agentpad";

const rt = new Runtime("./my-project");

const r = await rt.run("python", "print(1 + 1)");
console.log(r.stdout, r.exitCode);

rt.close();

Read-only workspace

Prevents writes through the library's fs adapter (engines still run shell/Python/Node; treat this as a library-level guard, not a kernel sandbox).

const rt = new Runtime("./repo", { readonly: true });
// rt.fs.writeFile(...) throws

Overlay mode

Copies the project to a temp directory. Runs and mutations happen there until you call apply(), which merges the temp tree back.

const rt = new Runtime("./repo", { overlay: true });
await rt.run("bash", 'echo "patched" > config.txt');
rt.apply(); // merges back into ./repo
rt.close();

Serialize overlay state

const data = rt.serialize();
rt.close();

const rt2 = Runtime.deserialize(data);

Next steps