Execute bash, Python, JavaScript (Node), and SQL against a real project directory—with optional overlay, read-only mode, file-change tracking, and a session run log. Built for AI agents, CI, and local tooling.
Same design in TypeScript (npm) and Python (PyPI / local install).
npm install agentpadRequires Node.js ≥ 18. For SQL on Node, the sqlite3 binary must be on your PATH.
pip install agentpadFrom a clone (editable):
pip install -e ./pythonRequires Python ≥ 3.10. For SQL in Python, the runtime uses stdlib sqlite3 (no sqlite3 CLI required).
import { Runtime } from "agentpad";
const rt = new Runtime("./my-project");
const r = await rt.run("python", 'print(open("README.md").read()[:80])');
console.log(r.stdout);
console.log(r.files); // file changes under the workspace
rt.close();from agentpad import Runtime
rt = Runtime("./my-project")
r = rt.run("python", "print(1 + 1)")
print(r.stdout)
rt.close()| Capability | Summary |
|---|---|
| Languages | bash, python, javascript, sql |
| Workspace modes | Normal, read-only (readonly: true), or overlay (temp copy + apply() back to disk) |
| File tracking | includeGlobs / excludeGlobs (minimatch) scope which paths appear in RunResult.files |
| Limits | timeoutMs, maxOutputBytes per run or via limits on the runtime |
| Session log | getRunLog(), clearRunLog(), exportRunLogJSON / exportRunLogMarkdown, optional onRun |
| OpenAI tools | asOpenAITool() + executeToolCall({ language, code }) (TS); as_openai_tool / execute_tool_call (Python) |
| Persistence | serialize() / Runtime.deserialize() for overlay state |
Hosted on slaps.dev:
| Doc | Contents |
|---|---|
| Overview | Product summary and doc index |
| Getting started | Install, first runs, overlay, read-only |
| Use cases | Agents, testing patterns, stubfetch |
| Configuration | RuntimeOptions, RunOptions, globs, limits, run log |
| API reference | Runtime, types, filesystem adapters, exports |
| Security | Threat model, workspace boundaries, subprocess behavior |
| Python notes | Node vs Python differences |
Package and issue tracker: github.com/vgulerianb/agentpad (canonical repo). The slaps.dev monorepo may carry a vendored copy of this tree for the website and doc sync scripts—it is not the package’s primary repository URL on npm/PyPI.
Apache-2.0