Persistent bash sandboxes over HTTP and MCP — backed by Postgres
Most sandbox platforms still spin up full VMs—slow cold starts and per-minute billing where costs stack up fast. just-bash is the virtual bash runtime; we built the distributed, persistent layer around it—a Postgres-backed virtual filesystem over HTTP and MCP, with strong consistency across replicas and fast in-process caching, so sandboxes that are cheap to create, quick to resume, and durable across process restarts.
Why
| Problem | Solution |
|---|
| Sandbox cost at scale is expensive with time-based pricing | State lives in your existing Postgres database — no per-minute sandbox billing, just the DB you already pay for |
| No isolation between agents | Row-level security (RLS) on sandbox_id — sandboxes are hard-isolated at the DB layer |
| Cold-starting a session re-fetches the entire filesystem from Postgres | Two-layer in-process cache: path map (0ms stat/readdir) + LRU content cache (0ms readFile on hit) |
| Concurrent requests from different replicas corrupt sandbox state | Stateless replicas + Redis distributed lock — only one replica runs exec for a sandbox at a time |
| Duplicate file content wastes storage | Content-addressable blob store (sha256-keyed) — identical files across all sandboxes share one row |
| Partial writes on script failure | Entire script runs in one DB transaction — it either fully commits or fully rolls back |
Quick Start
With Postgres
cp .env.example .env # set DATABASE_URL and AUTH_SECRET
pnpm db:migrate # apply migrations
pnpm dev # server at http://localhost:8080
Docker Compose
docker-compose -f docker-compose.local.yml up
Typical Agent Workflow
pip install sql-fs-sdk
from sqlfs import Client
import pathlib
client = Client(
base_url="http://localhost:8080",
auth_secret="localdev", # exchanges for a JWT automatically
sub="agent-001",
)
# 1. Create sandbox
sb = client.sandboxes.create(name="my-project")
# 2. Ingest project files
files = {str(p): p.read_bytes() for p in pathlib.Path("src").rglob("*") if p.is_file()}
sb.ingest_files(files, base_path="/home/user/src")
# 3. Run commands — stdout/stderr stream back
result = sb.exec("grep -r 'TODO' /home/user/src || echo 'no TODOs found'")
print(result.stdout)
# 4. Export modified sandbox (tar + base64 via exec — no dedicated HTTP endpoint)
import base64
r = sb.exec("tar -czf - -C /home/user/src . | base64 -w 0", read_only=True, timeout_ms=60_000)
pathlib.Path("result.tar.gz").write_bytes(base64.b64decode(r.stdout.strip()))
# 5. Cleanup
sb.delete()
How It Works
Postgres is always the source of truth. Everything else is a cache or a lock.
Each exec call flows through three stacked locks — in-process mutex → Redis distributed lock → pg_advisory_xact_lock — ensuring only one writer touches a sandbox at a time across any number of replicas. Writes always go to Postgres first; in-process caches (pathCache Map, contentCache LRU) and Redis (blob cache, path snapshot) are updated after and exist purely for speed.
Cross-replica coherence uses a single monotonic version counter in Redis — no pub/sub needed. When a replica acquires the exec lock and finds the counter advanced, it reloads pathCache from Postgres before proceeding.
Note: The /files/* HTTP endpoints bypass the exec lock. Use exec for all agent and production file access; the file API is for admin and test use only.
Schema
sandboxes id (UUID PK), root_inode, owner, created_at
│
inodes id (BIGSERIAL PK), sandbox_id, kind (file|dir|symlink),
mode, size, mtime, nlink, content_sha256 → blobs, symlink_target
│
dirents parent_inode_id, name, inode_id, sandbox_id
PK: (parent_inode_id, name) ← adjacency list; mv is O(1)
│
blobs sha256 (PK), data, size ← content-addressable; global dedup
Key design choices:
- Adjacency list —
mv of an entire directory subtree is one UPDATE row, not O(n)
- Content-addressable blobs — identical files across all sandboxes share one blob row
- RLS on
sandbox_id — isolation enforced at the database layer, not just the application
Environment Variables
