Corral

Appearance

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:

sh
corral start my-worker

Stop it:

sh
corral stop my-worker

Restart it (picks up wrangler config changes):

sh
corral restart my-worker

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

sh
corral up

Stop everything:

sh
corral down

Check what's running:

sh
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:

sh
corral settings set port-range-start 9000

Auto-Start ​

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

sh
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. 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)

The PORT environment variable is set to the allocated port for options 1 and 2, so most frameworks pick it up automatically.

sh
# 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.