execpad
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).
Install
JavaScript / TypeScript (npm)
npm install execpad
Requires Node.js ≥ 18. For SQL on Node, the sqlite3 binary must be on your PATH.
Python
pip install execpad
From a clone (editable):
pip install -e ./python
Requires Python ≥ 3.10. For SQL in Python, the runtime uses stdlib sqlite3 (no sqlite3 CLI required).
Quick start
TypeScript
import { Runtime } from "execpad";
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();
Python
from execpad import Runtime
rt = Runtime("./my-project")
r = rt.run("python", "print(1 + 1)")
print(r.stdout)
rt.close()
Features
| 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 |
Documentation
| Doc | Contents |
|---|---|
| Getting started | Install, first runs, overlay, read-only |
| 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 |
License
Apache-2.0
Metadata
Release files for execpad 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| execpad-0.1.0.tar.gz | 6.2 kB | Without provenance | Details for execpad-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| execpad-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for execpad-0.1.0-py3-none-any.whl |
Total release size: 14.3 kB
Release files / execpad-0.1.0.tar.gz
| Download URL | execpad-0.1.0.tar.gz |
|---|---|
| Size | 6.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
882c73ddd2d104b2d32edba4eabca4ad524fd2e62e4ce70e3430ee9ac657d6bc
|
|
BLAKE2b-256 checksum How to use checksums |
a67308a40f4ce18ca1a5c4cb450eca3645f156eec06111ac4a6223d5e4328291
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
Hatch/1.16.5 cpython/3.14.3 HTTPX/0.28.1
|
Release files / execpad-0.1.0-py3-none-any.whl
| Download URL | execpad-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
31b07d385a7cb82e3d8c84e886fa818052d096457ebe9811629c1693fe6464f4
|
|
BLAKE2b-256 checksum How to use checksums |
4ec437f5581931ba033a23c536aef6434510a05747cd69f68d91c92762b4be6a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
Hatch/1.16.5 cpython/3.14.3 HTTPX/0.28.1
|
Security for execpad 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.