Local Development

Corral manages dev server processes for your projects. It handles port allocation, ready detection, crash recovery, and graceful shutdown — so you can focus on writing code.

Starting and Stopping Projects

Start a single project:

corral start my-worker

Stop it:

corral stop my-worker

Restart it (picks up wrangler config changes):

corral restart my-worker

Retry a failed project (clears the failure and attempts to start again):

corral retry my-worker

The retry command is specifically for projects in a failed or abandoned state. It clears the failure record, resets the crash-loop counter, and runs the start path fresh. Use restart for a running project that needs to pick up config changes; use retry when a project has failed and you’ve fixed the underlying issue.

Start everything — infrastructure plus all projects flagged for auto-start:

corral up

Stop everything:

corral down

Check what’s running:

corral status

This shows the state of DNS and proxy services, plus a table of running projects with their ports, Node.js versions, and status.

Network Access

By default, dev servers bind to 127.0.0.1 (localhost only). To make a project accessible from other devices on your local network — like a phone for mobile testing — use the --host flag:

corral start my-worker --host
# ok Started my-worker
#    network http://192.168.1.100:8787

This binds the dev server to 0.0.0.0 instead of 127.0.0.1, making it reachable at your machine’s LAN IP address. The .test domain and HTTPS continue working on your Mac as usual — they just won’t resolve on other devices.

Network access is ephemeral: it applies only to the current run and resets when the project stops. To restart a running project with network access:

corral restart my-worker --host

In the macOS app, use the ellipsis menu (three-dot button) next to the play/stop button in the toolbar. It offers “Serve on Network” to start or restart with network access, and “Disable Network Access” to switch back.

Sharing to the Internet

To make a project accessible from anywhere — not just your local network — use tunnel sharing:

corral share my-worker
# ok Sharing my-worker
#    public https://random-words.trycloudflare.com

This creates a public HTTPS URL via a Cloudflare Quick Tunnel. Anyone with the link can reach your dev server. Useful for:

• Showing work to a teammate or client
• Testing webhooks from external services (Stripe, Twilio, etc.)
• Cross-device testing when the device isn’t on your network

The URL is ephemeral — it changes when the project restarts or you stop and re-share. To stop sharing:

corral share my-worker --stop

If the project isn’t running when you share it, Corral starts it first automatically.

In the macOS app, use the ellipsis menu (three-dot button) in the toolbar. “Share to Internet…” starts the tunnel; “Stop Sharing” tears it down. The shared URL appears in the project’s overview with a copy button.

First-time use: Corral downloads the cloudflared binary (~30 MB) on your first share. Subsequent shares start instantly.

No Cloudflare account is needed. Sharing is free and has no bandwidth limits for development use.

Port Allocation

Corral automatically assigns a port to each project from a configurable range. The defaults are:

• Start port: 8787
• Pool size: 100 ports (8787–8886)

Before allocating a port, Corral checks that it’s not already in use by another process. Ports are released when a project stops.

You can change the start port in Configuration:

corral settings set port-range-start 9000

Auto-Start

Flag projects that should start automatically when you run corral up:

corral project set my-worker auto-start true

When auto-start is enabled in app settings, corral up (or launching the macOS app) will start infrastructure and all flagged projects.

Process Lifecycle

All project processes are managed by a background daemon. This means both the CLI and the macOS app see the same running state — a project started via corral start is immediately visible in the app’s UI, and vice versa.

Projects, services, and infrastructure components (DNS, proxy, helper) are all managed as units — discrete managed entities with their own lifecycle and health state. A unit’s lifecycle can be:

• Pending — registered but not yet started
• Active — running (with phases: Starting, Initializing, Ready, Reloading, Stopping)
• Idle — stopped intentionally
• Failed — encountered an error (with structured failure details)
• Abandoned — stopped retrying after repeated failures

When Corral starts a project, it transitions through these active phases:

1. Starting — port allocation and dev command resolution
2. Initializing — spawning the process with the correct Node.js version and port
3. Ready detection — watching process output for ready signals and performing HTTP health checks
4. Ready — the project is serving requests
5. Stopping (when requested) — sends graceful termination signal, waits before forcing a stop

Units also track health independent of lifecycle. A project can be Active/Ready but Degraded (e.g., a linked service is down) or Critical (e.g., DNS infrastructure failed). Health signals surface in the UI as warning banners and can stack — multiple failed services each add their own signal.

Dev Command Resolution

Corral determines what command to run in this order:

1. Custom dev command — if you’ve set one via corral project set <project> dev-command "...", it’s used
2. package.json dev script — if the project has a "dev" script in package.json, Corral runs it via the detected package manager (e.g., npm run dev, pnpm dev, yarn dev)
3. Framework default — if neither of the above applies, Corral uses the framework’s built-in command (e.g., wrangler dev, next dev, vite)

For options 1 and 2, the PORT environment variable is set and framework-specific port flags (e.g., --port for Astro/Vite, -p for Next.js) are appended to the command automatically. This ensures the dev server listens on the Corral-allocated port.

# Set a custom dev command
corral project set my-app dev-command "npm run dev"

# Clear it (revert to auto-detection)
corral project set my-app dev-command none

Ready Detection

Corral knows a project is ready by two methods:

• Log pattern matching — watches stdout for a framework-specific “ready” message
• HTTP health check — periodically sends requests to http://localhost:{port} until it gets a response

Failure Recovery

If a process crashes unexpectedly, Corral automatically attempts to restart it with exponential backoff. After repeated failures, the unit enters a Failed state with structured failure details — the kind of failure (port in use, readiness timeout, insufficient disk space, etc.), a diagnostic message, and suggested remediation actions.

Failures are persisted to a per-unit ledger at ~/.corral/units/<id>/failures.jsonl (capped at 10 MB, with the most recent 1000 entries kept on daemon startup). Each failure records a snapshot of the unit’s logs at the time of failure, accessible via the Failure History tab in the macOS app or the corral status --json output.

When a unit fails due to an upstream dependency (e.g., a project fails because a linked service crashed), the failure is marked as a cascade failure. The macOS app renders a failure chain that links the downstream failure back to its root cause, and the log snapshot points to the upstream unit’s logs rather than duplicating them.

Orphan Cleanup

On startup, Corral scans for any orphaned processes left behind from a previous session (e.g., after a crash) and cleans them up.

Vendored Wrangler

Corral ships with its own copy of Wrangler, currently pinned to version 3.114.1. This means:

• You don’t need to install Wrangler globally
• Corral uses a tested, known-good Wrangler version
• Your global Wrangler installation (if any) is not affected

Corral automatically configures Wrangler with the correct port, environment, protocol, and Node.js version for each project.