forkstack 0.1.0

forkstack CLI - instant, isolated development environments using zero-copy database and storage forks

forkstack

Instant, isolated development environments using zero-copy database and storage forks.

forkstack is a CLI tool for creating fully isolated development environments in seconds. Each developer gets their own copy of your entire stack—database and object storage—without duplicating data or slowing down.

Installation

# Recommended: install script
curl -LsSf https://forkstack.xyz/install.sh | sh

# Or with pip/uv
pip install forkstack
uv pip install forkstack

# Or with cargo
cargo install forkstack --bin forks

Why forkstack?

Traditional development environments share databases or require expensive duplication:

• ❌ Shared dev DB: Developers step on each other's data
• ❌ DB per developer: Expensive, slow to provision, hard to keep in sync
• ❌ Local-only: Can't test with production-like data

forkstack gives you the best of all worlds:

• ✅ Instant creation: New environments in seconds, not minutes
• ✅ Zero cost: Fork-on-write means no data duplication charges
• ✅ Full isolation: Each environment has its own DB and storage
• ✅ Production parity: Fork from production to test with real data
• ✅ Easy cleanup: Delete environments instantly when done

Quick Start

1. Create a config file

Create .forkstack.toml in your project:

[database]
provider = "turso"
organization = "your-org"
production = "my-app-prod"

[storage.uploads]
provider = "tigris"
bucket = "my-app-uploads"
endpoint = "https://fly.storage.tigris.dev"

2. Set credentials

export TURSO_API_TOKEN="your-token"
export AWS_ACCESS_KEY_ID="your-key"
export AWS_SECRET_ACCESS_KEY="your-secret"

3. Create a fork

$ forks create -n alice
Created fork: alice
Database: libsql://alice-your-org.turso.io
Storage:  uploads: s3://my-app-uploads/forks/alice/

4. Use your fork

Point your app at the fork URLs, work in isolation, then clean up:

$ forks delete alice
Deleted fork: alice

CLI Reference

forks create           # Create fork with random name
forks create -n alice  # Create fork with specific name
forks list             # List all forks
forks delete alice     # Delete a fork

How It Works

forks create
    │
    ├── Turso API: Create database branch
    │   └── Zero-copy fork from production DB
    │
    └── S3 API: Copy objects to fork prefix
        └── Full copy (or use Tigris bucket forks)

Database branching uses Turso's native branching—instant, zero-copy regardless of database size.

Storage forking copies objects to a fork-specific prefix. For zero-copy storage, use Tigris bucket forks.

Supported Services

Databases (pick one):

• Turso - SQLite branches (recommended)
• More coming soon (Neon, PlanetScale)

Object Storage (pick one):

• Tigris - S3-compatible with bucket forks (recommended)
• Any S3-compatible storage

Pattern Benefits

For Individual Developers

• Test risky changes in isolation
• Work on multiple features simultaneously
• Fork from prod to debug with real data
• Clean up experiments instantly

For Teams

• No database conflicts between developers
• Easy code review with deployable branches
• Staging environments on-demand
• Safe production debugging

For CI/CD

• Ephemeral preview environments per PR
• Cost-effective testing at scale
• Automatic cleanup after merge

Documentation

Full documentation at forkstack.xyz

• Getting Started Guide
• Architecture Deep Dive
• Database Options
• Storage Options

Contributing

Contributions welcome! Submit issues and PRs at github.com/russellromney/forkstack

License

Apache 2.0 - Use it however you want.