Parcela

Parcela manages an explicit service set belonging to one adopted checkout. Caddy owns HTTPS routing. Process Compose owns application processes and workers. Project configuration owns commands, working directories, dependencies, writable resources and external effects.

This skill does not grant permission to start services, process queues, run migrations, change trust or expose a listener. Follow the user’s authorization and the project’s instructions. Do not print credentials, .env contents, native tokens or full process environments.

Learn and select the target

Use the same binary and registry for discovery and subsequent operations. Check unfamiliar syntax with parcela --help or the relevant command’s --help. parcela --skill and parcela skill print this bundled document without reading project or registry state.

Set CHECKOUT to the intended existing checkout’s absolute path. Do not infer the target from a focused terminal, bookmark or branch name.

parcela workspace list --all
parcela --path "$CHECKOUT" config check
parcela --path "$CHECKOUT" context
parcela --path "$CHECKOUT" status

workspace list --all returns .workspaces, each containing .workspace.id, .workspace.source, .workspace.role and live status. context requires an adopted configured checkout and returns its identity, planned URLs and caveats. Read its parcela.yaml and project instructions before a mutation. Schema validation and planned URLs do not prove readiness or data isolation.

For a registered target, read its UUID from the response. Prefer that exact ID when issuing later operations from a different directory:

parcela --workspace "$ENVIRONMENT_ID" status
parcela --workspace "$ENVIRONMENT_ID" services

--path and --workspace conflict. Keep an explicit --state-dir prefix on every call if using a nondefault registry. UUID targeting does not select another machine. Missing source paths do not authorize source or registry deletion.

For unregistered sibling checkouts, workspace discover is read-only VCS discovery. Adoption is separate. Only when the user authorizes adoption, set ROLE and LABEL to their chosen role and label:

parcela --path "$CHECKOUT" workspace adopt --role "$ROLE" --label "$LABEL"

Use primary only when explicitly intended. Parcela does not create a worktree or change VCS history during adoption. A preview role and distinct URLs do not isolate databases, uploads, secrets or queues. Refuse startup until the project’s bindings and external-effect policy are appropriate for the selected environment.

Start and verify

Check the configured dependencies and owned front door before startup:

parcela proxy status
parcela --path "$CHECKOUT" status

If already ready, reuse the environment unless the user requests a restart. If prerequisites are absent, report them. Do not automatically install backends, start Docker or a GUI, reuse another agent’s dependencies, repair forwarding, trust a CA, change global firewall rules or take over listeners. Do not open an installed registry for writing with a newer binary while an older proxy or controller still serves it; an upgrade requires an explicit coordinated plan.

After authorized startup, use detached mode for agent operations:

parcela --path "$CHECKOUT" up --detach
parcela --path "$CHECKOUT" status
parcela --path "$CHECKOUT" services
parcela --path "$CHECKOUT" url
parcela --path "$CHECKOUT" url --service backend

Use a declared service name instead of assuming every project has backend. up starts the whole native graph. run -- ARGV is a literal foreground command for a single HTTP service, not a substitute for a service-set graph. --backend-port selects the default service only. Do not assume a fixed backend port.

Each run has one generation and nonce with a recorded endpoint set. All declared HTTP endpoints must have graph-owned loopback listeners and pass initial readiness before the group routes open. Non-HTTP workers belong in the native graph and need no route. Per-service working directories and PORT overrides belong in native Process Compose entries.

Inspect status.state and status.live.endpoints. live_health_verified means the owner answered, not that every HTTP probe succeeded. Recorded ready, planned URLs and native Running states are not interchangeable with fresh HTTP health. Check the intended application path over its returned HTTPS origin when the task needs application proof. Never disable TLS verification to make a check pass.

Report the selected environment ID, role, generation, returned URLs, observed health and unverified behavior. Leave user-managed environments running unless stop was requested.

Diagnose without guessing ownership

parcela --workspace "$ENVIRONMENT_ID" status
parcela --workspace "$ENVIRONMENT_ID" services
parcela --workspace "$ENVIRONMENT_ID" logs backend --tail 100

Read process names from services before selecting logs. A legacy single-service graph can have a different process name from its routed service. Logs are bounded tails, not a follow stream. Avoid copying secrets from diagnostics.

unknown, interrupted, missing evidence or a replaced native handle is not permission to clear locks, delete sockets, free leases or kill a process. Never signal a persisted PID, use broad pkill, or bypass the owner through raw native commands. Preserve the diagnostic and ask for an explicit recovery or manual intervention plan.

When the owner has died and the task authorizes recovery of a proven native graph:

parcela --workspace "$ENVIRONMENT_ID" recover --detach
parcela --workspace "$ENVIRONMENT_ID" status

Recovery requires matching generation, process births, original lock/socket identities and native authentication. It uses the recorded launch manifest and does not replay startup. A pending stop remains a stop; a successful recovered result can be stopped rather than ready. Do not retry by launching a duplicate graph when recovery refuses.

Restart, stop and project tasks

Only for the explicitly selected authorized environment:

parcela --workspace "$ENVIRONMENT_ID" restart --detach
parcela --workspace "$ENVIRONMENT_ID" status
parcela --workspace "$ENVIRONMENT_ID" down
parcela --workspace "$ENVIRONMENT_ID" status

Restart preflights the replacement and starts the whole graph in a new generation. It does not restart one named service or replay arbitrary run commands. Stop withdraws routes before native shutdown and preserves source/data. Do not stop other environments as test cleanup. Do not treat a refused or incomplete stop as successful cleanup.

Before task NAME -- ARGS, read that task’s argv, timeout and effects in parcela.yaml. Run only the requested task with literal arguments. Startup does not imply permission for setup, migrations, resets, seeds, imports or code generation. Do not invent framework preparation commands.

The default service uses the environment base hostname. Other HTTP services use a flat prefix from subdomain or the service name. For a preview labeled review of my-app, typical names are review-my-app.localhost and api-review-my-app.localhost. Read actual reserved or recorded URLs instead of constructing them. Hostname reservations remain while stopped; changing them requires a stopped environment and explicit re-adoption.

Limits

This is an experimental local runtime manager, not a sandbox, terminal multiplexer or automatic active-agent handoff system. It does not automatically reconcile allocations missing launch evidence, adopt arbitrary orphan processes, restart individual services, create data replicas or certify reboot/browser trust. A skill, command help or configuration document is not runtime proof.