Configuration

Corral stores its settings in ~/.corral/config.json. You can view and change them from the CLI or the macOS app.

App Settings

Setting	Key	Default	Description
TLD	tld	test	Top-level domain for local routing
Auto-start	auto-start	false	Start infrastructure and flagged projects on launch
Default Node version	default-node-version	(none)	Fallback Node.js version when no project-specific version is set
Port range start	port-range-start	8787	First port in the allocation pool (100 ports)
Default package manager	default-package-manager	(none)	Used when nothing earlier in the resolution chain answered — for the dev server and the Dependencies tab as well as corral pm
Serve at login	serve-at-login	true	Whether the daemon started by the login agent brings DNS and the proxy up, claiming ports 80 and 443. A daemon a CLI command spawned lazily never claims them regardless
Lazy start default	lazy-start-default	true	Fallback for a project with no setting of its own: whether visiting a stopped project’s .test URL starts it, instead of only showing the down-page
Preferred browser	preferred-browser	(system default)	Browser bundle ID for opening local dev URLs (e.g. com.google.Chrome)
Preferred editor	(macOS app)	(chooser)	Editor bundle ID for Open in Editor; set in the macOS app, not via corral settings set
Preferred terminal	(macOS app)	(Terminal.app)	Terminal bundle ID for Open in Terminal; set in the macOS app, not via corral settings set
Log font size	ui.logs.font_size	11	Monospaced font size in the log viewer
Log word wrap	ui.logs.word_wrap	true	Whether long log lines wrap in the log viewer

Viewing Settings

corral settings show

Changing Settings

corral settings set tld localhost
corral settings set auto-start true
corral settings set default-node-version 22
corral settings set port-range-start 9000
corral settings set default-package-manager pnpm
corral settings set preferred-browser com.google.Chrome

Clear optional settings with none:

corral settings set default-node-version none
corral settings set preferred-browser none

Boolean values accept: true/false, yes/no, 1/0, on/off.

In the macOS app, settings are available under the Settings panel in the sidebar. See macOS App Settings for details.

A few preferences are managed only in the macOS app (and config.json), not via corral settings set — notably Corporate proxy support (Settings → Network & Security), which controls automatic corporate-CA detection for Node tooling behind a TLS-intercepting proxy. See Node.js Management → Corporate proxies.

Data Directory

All Corral data lives in ~/.corral/:

Path	Contents
config.json	App-wide settings
projects.json	Registered projects and their settings
corral.sock	Daemon Unix socket (JSON-RPC 2.0)
daemon.pid	Daemon process ID
daemon.log	Daemon operational log
runtimes/node/{version}/	Installed Node.js versions (a legacy node/ tree is migrated on first boot)
tools/node/{node_version}/wrangler/{version}/	Wrangler installs, keyed on the Node version they run under (a legacy wrangler/v{version}/ tree is migrated)
caddy/	Caddy configuration and certificate files
dnsmasq/	dnsmasq configuration files
services/	Installed service binaries, data, and registry. Layout is <service>/<version>/ so that concurrent major versions (e.g. Postgres 16 and 17) stay isolated — see Services → Data Directory for the full tree.
logs/	Persisted log files (per project)
shims/	Shell shims for node, npm, npx — the ones that shadow a command you may already have
bin/	The cpm shim, and a copy of the corral CLI until the privileged helper has been approved (after that it lives machine-wide and this copy is removed)
libexec/	corral-shim-fallback — the one script every shim hands off to when no corral is available. Kept off your PATH on purpose, unlike the two directories above

Files in your project directory

One feature writes outside ~/.corral/. Enabling the Pro sidecar, which powers live Durable Object method invocation, adds a .corral/ directory and a token block in .dev.vars to that project, and appends both to its .gitignore. Nothing else Corral does touches your project files.

Environment Variables

CORRAL_DATA_DIR

Override the data directory location:

export CORRAL_DATA_DIR=/path/to/custom/dir
corral status

Or pass it per command:

corral --data-dir /path/to/custom/dir status

This affects where Corral reads and writes all data — settings, projects, Node.js installations, logs, and infrastructure configuration.

NODE_EXTRA_CA_CERTS

Set automatically by Corral for the Node processes it spawns when corporate-CA detection finds corporate roots, so Node tooling works behind a TLS-intercepting proxy. You normally never set this by hand — but if you already export it yourself, Corral folds your certificates in rather than overriding them.

CORRAL_REPORTS_ENDPOINT

Advanced override for the bug report submission endpoint (for staging or end-to-end testing). Defaults to https://api.corral.sh/v1/reports.