Projects

A project in Corral is any JavaScript/TypeScript application you’ve registered for local development. Corral detects the framework, assigns a local subdomain, and manages the dev server lifecycle.

Registering a Project

CLI:

corral project add ./my-worker

macOS App: Click the + button in the toolbar and select a folder, or drag a project folder onto the main window. Either way, the project is registered and automatically selected in the sidebar.

Corral will:

1. Detect the framework (see below)
2. Read the project name from wrangler.toml/package.json
3. Generate a URL-safe subdomain from the project name (e.g., my-worker)
4. Assign a unique ID for internal tracking
5. Detect the git remote URL if the directory is a git repository (GitHub, GitLab, Bitbucket, or any self-hosted host)

If the subdomain would collide with an existing project, Corral appends a suffix (my-worker-2, my-worker-3, etc.).

Framework Detection

Corral detects your project’s framework automatically using a priority-based chain:

Priority	Framework	Detected By
1	Cloudflare Worker	wrangler.toml, wrangler.json, or wrangler.jsonc
2	Next.js	next in package.json dependencies
3	Nuxt	nuxt in package.json dependencies
4	Remix	@remix-run/dev in package.json dependencies
5	Astro	astro in package.json dependencies
6	SvelteKit	@sveltejs/kit in package.json dependencies
7	Gatsby	gatsby in package.json dependencies
8	Angular	@angular/core in dependencies + angular.json file
9	Vite	vite in package.json dependencies
10	Generic Node.js	Any package.json with a dev or start script

The first match wins. A project with both wrangler.toml and vite in its dependencies will be detected as Cloudflare.

Visual Identity

When a project is registered, Corral also tries to discover its icon and brand color so the catalog has a recognizable visual identity:

• Icon — searched in this order: web manifest icons (public/manifest.webmanifest, public/manifest.json, static/ equivalents), Next.js conventions (app/icon.*, app/apple-icon.*, app/favicon.ico), and generic favicons (public/favicon.{svg,png,ico}, public/logo.{svg,png}, and the same paths under static/).
• Brand color — parsed from the manifest’s theme_color field (hex, rgb()/rgba(), hsl(), or any named CSS color).

Inferred icons are copied into Corral’s data directory at registration so the catalog never depends on the original file remaining in place. SVG icons are rasterized to a 512×512 PNG alongside the original for crisp rendering at any size.

If nothing is found, the project renders with an initials avatar — one or two letters on a deterministic palette color hashed from the project name.

You can override either in the macOS app under Settings → Appearance.

Scanning for Projects

If you keep your projects in a common parent directory, scan it to find them all at once:

corral project scan ~/code

This lists every immediate subdirectory that contains a recognized project. You can then register them individually.

What Gets Parsed (Cloudflare Projects)

For Cloudflare projects, Corral reads the wrangler configuration in detail. This includes:

Project identity:

• name, main, compatibility_date, compatibility_flags
• Project type detection: Worker (has main), Pages (has pages_build_output_dir), Durable Object (has DO bindings)

Bindings:

• D1 Databases, KV Namespaces, R2 Buckets, Durable Objects, Workflows
• Queues (producers and consumers), Service Bindings
• AI, Vectorize, Hyperdrive, Analytics Engine, Secrets Store

Additional configuration:

• Cron triggers, build commands, dev server settings
• Observability, CPU limits, routes, environment variables

Environments:

• Named environments defined under [environments] are detected and available for selection
• When you select an environment, its overrides are merged with the top-level configuration

Per-Project Settings

Each project has settings you can customize:

Setting	Description	Default
node-version	Node.js version override	Resolved via version chain
subdomain	Custom subdomain for domain routing	Auto-generated from project name
environment	Wrangler environment to use	None (uses top-level config)
auto-start	Start automatically with corral up	false
dev-command	Custom dev command override (e.g., npm run dev)	Auto-detected
package-manager	Preferred package manager (npm, yarn, pnpm, bun)	Auto-detected from lockfile
address-mode	How the project is served: proxy (.test), localhost (HTTP), or localhost-tls (HTTPS)	proxy
localhost-port	Front-door port for a localhost address mode (none to auto-pick)	Auto-assigned
serve-proxy-route	Keep the .test route alongside localhost (false = localhost-only)	true
Custom icon	Image displayed in the catalog (set in the macOS app)	Auto-inferred or initials avatar
Custom color	Brand color used behind the icon (set in the macOS app)	theme_color from manifest, else palette hash
Preferred browser	Browser for this project’s URLs, overriding the app default (set in the macOS app)	Inherit app default
Preferred editor	Editor for Open in Editor on this project, overriding the app default (set in the macOS app)	Inherit app default
Preferred terminal	Terminal for Open in Terminal on this project, overriding the app default (set in the macOS app)	Inherit app default

Set them via the CLI:

# Pin a Node.js version for this project
corral project set my-worker node-version 22

# Use a custom subdomain
corral project set my-worker subdomain api

# Select a wrangler environment
corral project set my-worker environment staging

# Start automatically with infrastructure
corral project set my-worker auto-start true

# Also serve at localhost:5173 (for apps that hard-code a localhost URL)
corral project set my-worker address-mode localhost
corral project set my-worker localhost-port 5173

Use none to clear an optional setting:

corral project set my-worker node-version none

Or configure them in the macOS app under the project’s Settings tab. The icon and color overrides are configured exclusively through the macOS app’s Appearance section, and the preferred browser/editor/terminal overrides through the Settings tab — none of these are exposed via corral project set.

Refreshing Configuration

If you edit your wrangler.toml, tell Corral to re-read it:

corral project refresh my-worker

This updates the parsed configuration without removing or re-registering the project. Your project settings (subdomain, Node version, etc.) are preserved.

Removing a Project

corral project remove my-worker

This unregisters the project from Corral. It does not delete any files in your project directory.

Viewing Project Details

corral project info my-worker

Shows the project’s ID, path, type, compatibility date, subdomain, canonical URL, git repository URL, current branch, settings, and detected bindings. Git information is only shown for projects with a detected git remote.

Project Resolution

Whenever a command takes a <project> argument, you can use:

• The project’s name (exact or substring match)
• The project’s UUID

If a substring matches multiple projects, Corral will ask you to be more specific.