Parcela

Deployable dev environments for your AI agents.

Documentation · Getting started · FAQ

Parcela runs a checkout's web servers, workers, and other services at named HTTPS URLs. Each jj workspace or Git worktree gets its own processes and ports, so several agents can test the app in parallel.

Parcela is experimental and supports macOS and Linux. It supervises native processes and uses Caddy for TLS and routing.

Start an existing app

curl -fsSL https://parcela.run/install.sh | sh
cd /path/to/your/project
parcela init

Review the generated parcela.yaml and its data settings. Then run:

parcela doctor
parcela up --detach

Open the URL in the output, such as https://shop.localhost:1443. The first terminal up offers CA trust behind the system password prompt. Scripts and agents never change system trust.

parcela logs shows process output. parcela down stops the environment and retains source and data.

For Homebrew and source builds, see Get started. Upgrades are in the FAQ. The getting started guide also has a setup prompt for coding agents.

Describe the whole stack

version: 1
project: shop

services:
  web:
    command: bin/rails server -p $PORT -b 127.0.0.1
    http:
      healthcheck: /up
  jobs:
    command: bin/jobs

hooks:
  setup:
    command: bin/setup

Each HTTP service receives a leased port through PORT. Routes open after readiness checks pass. Setup runs until it succeeds once in each environment. Your configuration decides how to install dependencies and separate databases, queues, and uploads.

The primary checkout uses https://shop.localhost:1443. A signup checkout uses https://signup-shop.localhost:1443. Additional HTTP services add their configured prefix. Sharing with another device requires --lan, --tailscale or --domain for that run.

Give an agent its own environment

From the configured project, create and start a named checkout:

parcela create experiment
parcela -w experiment up --detach
parcela -w experiment down

Parcela creates a jj workspace or detached Git worktree and registers its preview name. Creation starts nothing. With declared data, snapshot and create --from reproduce a stopped environment's dataset from explicitly declared files, with consistent SQLite backups. See worktrees and agents.

Parcela sends anonymous command telemetry unless disabled. Run parcela telemetry disable to turn it off. Telemetry lists the fields and controls.

Documentation

Start with the documentation index.

• Get started with your app, or build the tutorial app.
• Configure a project and run parallel worktrees.
• Look up CLI commands and configuration fields.
• Read environment boundaries and the FAQ.
• Contribute, inspect the architecture, or read the changelog.

License

Copyright © 2026 LOST COORDS. Parcela is licensed under the GNU Affero General Public License, version 3 only. See COPYRIGHT for the project notice and third-party terms.