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

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.

When Corral starts a project, it goes through these stages:

1. Port allocation — prefers the framework's default port (e.g., 4321 for Astro, 3000 for Next.js), falls back to a pool starting at 8787
2. Dev command resolution — determines what to run (see below)
3. Spawning — launches the dev command with the correct Node.js version and port
4. Ready detection — watches the process output for a ready signal and performs HTTP health checks
5. Running — the project is serving requests
6. Shutdown — when stopped, Corral sends a graceful termination signal and waits before forcing a stop

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

Auto-Restart

If a process crashes unexpectedly, Corral will automatically attempt to restart it. After a configurable number of failed restart attempts, the project enters an errored state.

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.