Local Development

Corral manages wrangler dev processes for your Cloudflare 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.

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

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

1. Port allocation — finds an available port
2. Spawning — launches wrangler dev with the correct Node.js version, port, and environment
3. Ready detection — watches the process output for a ready signal and performs HTTP health checks
4. Running — the project is serving requests
5. Shutdown — when stopped, Corral sends a graceful termination signal and waits before forcing a stop

Ready Detection

Corral knows a project is ready by two methods:

• Log pattern matching — watches stdout for wrangler's "Ready on" message
• HTTP health check — periodically sends requests to http://localhost:{port} until it gets a response

Auto-Restart

If a wrangler 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 wrangler 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.