Working with Projects

When you select a project in the sidebar, the detail area shows a tabbed interface with six tabs: Overview, Dependencies, Network, Logs, Failure History, and Settings.

Overview Tab

The Overview tab is the project’s home page. It opens with a URL hero, then a stats strip, then the repository and share cards, and — for Cloudflare projects — finishes with the bindings region.

Toolbar

The toolbar shows project-specific actions:

• Restart button (when running) — restarts the project atomically
• Start/Stop button — starts or stops the project
• More menu (ellipsis icon) — additional actions:
  • Share via Tunnel… — creates a public tunnel URL for the project (downloads cloudflared on first use; auto-starts a stopped project before tunnelling)
  • Stop Sharing — tears down the tunnel (when actively shared)
  • Serve on Network / Start with Network Access — starts or restarts the project bound to 0.0.0.0 so other devices on the local network can reach it (disabled while sharing is active)
  • Disable Network Access — restarts without network binding (disabled while sharing is active)

URL Hero

The protagonist of the Overview tab. The hero card carries the project’s identity and runtime state at the same time:

• 48pt project mark — the project’s brand icon (auto-detected favicon, manifest icon, or initials avatar). The mark is constant across states; it identifies the project, not its runtime.
• State-driven gradient — the card’s surrounding wash and border take their tint from the run state: green when running, yellow when starting or stopping, red when failed, the system accent color when stopped (a stopped project is “ready to start”; the accent color reads as a default/prominent UI cue).
• Live dot + status sentence — a small indicator dot and one of:
  • Running · 17 min · … (uptime)
  • Stopped or Stopped · last ran 2h ago
  • Failed — port 8787 in use (structured failure message with remediation action)
  • Starting… (with optional progress sub-line like Resolving Node version…)
  • Stopping…
• Structured failure block — when a project is in Failed state, the hero expands to show a StructuredFailureBlock — a remediation-first UI that displays the failure kind, a diagnostic message, and actionable buttons (Retry, View Logs, View Failure History). Cascade failures (failures triggered by an upstream dependency) render a failure chain that links to the root cause.
• Primary URL — your project’s canonical URL, shown in Cloudflare orange for Workers and the system accent color for everything else. It opens in your preferred browser. When the project is stopped, the URL stays visible (muted) but isn’t clickable.
• Mono URL list — small monospaced rows below the primary URL:
  • localhost: 8787 and network: 192.168.1.100:8787 (only while running)
  • node: 22.14.0, compat: 2026-03-10, wrangler: 3.114.1 (config-derived; visible in any state)

Stats Strip

A row of equal-width metadata cards rendered between the hero and the next section. The schema depends on project type:

Project type	Cards
Cloudflare	Worker type · Compatibility · Wrangler · Dependencies
Everything else	Framework · Dependencies

The Dependencies card shows Up to date, N outdated (in amber when at least one dep is outdated), Checking… while the count is in flight, or — when the count is unavailable. The branch and last-commit cards from the previous design were removed — both surface in the Repository panel below in a richer form.

Repository

If the project is a git repository, the Repository panel shows up to three rows:

• Origin — the remote URL (host + path, e.g. github.com/you/repo) with an Open on GitHub / Open on GitLab / Open on {host} link.
• Branch — the current branch name (or short commit hash with (detached) in detached-HEAD state). When the branch tracks an upstream, an N ahead, N behind, A ahead · B behind, or in sync hint appears at the right.
• Last commit — short hash, the commit subject in italics, and a relative timestamp (e.g. 2h ago).

The panel self-elides when there’s no remote or branch info available, so projects without git just don’t render it.

Share Card

The share card transforms in place across three states; the share verb keeps a consistent slot through the project’s tunnel lifecycle:

• Not shared — dashed border, indigo-tinted globe glyph, “This dev server isn’t shared publicly” with a Share via tunnel ↗ CTA in the system accent color.
• Setting up — appears the instant you start a share and stays through the cloudflared URL negotiation (typically 2–5 seconds). Border tightens to solid indigo at low opacity, the glyph slot replaces with a spinner, the sentence reads Setting up tunnel…, the CTA disappears.
• Sharing — solid indigo low-opacity border with a faint indigo wash, Shared at <tunnel-url> with the URL as a mono link, plus a copy-icon button and a Stop sharing link. A tunnel URL is reachable before its data plane is — and on restrictive networks (corporate firewalls often block the outbound UDP that the tunnel’s QUIC transport uses) it may never connect — so Corral keeps probing the live URL while shared and shows the verdict on a connectivity row beneath it, updating automatically:
  • Verifying connectivity… — spinner glyph; the URL is up but not yet confirmed to round-trip.
  • Reachable — filled globe glyph and a green check; the URL serves through the tunnel to the dev server.
  • May be unreachable — amber warning-triangle glyph; the probe couldn’t reach the URL, so the network is likely blocking the tunnel. The URL stays visible and copyable, and the row flips back to Reachable on its own if a later HTTP/2 fallback connects.

Bindings Region

Cloudflare Workers render a five-group bindings region below the share card. Only groups that contain at least one binding are shown; a Worker with zero bindings hides the region entirely.

Group	Types
Storage	D1, R2, KV, Hyperdrive
Compute	Durable Objects, Workflow
Intelligence	AI, Vectorize
Async & security	Queue, Secrets
Telemetry & environment	Service, Analytics, Var

Each tile has a colored mark (per-type brand color), a binding name, and a vital sign — table count, key count, object count, instance count, and so on. Tiles for D1, R2, KV, Durable Objects, Workflow, and Secrets are clickable doorways into a data browser sheet (see Binding Browsers below). Right-click any tile for Inspect (opens the browser), Copy Binding Name, and Copy Resource ID. The other types — AI, Vectorize, Queue, Service, Analytics, Var, Hyperdrive — render as type-aware tiles without a click-through; their data lives outside Corral’s local probes.

The grid is adaptive at 280pt per tile, so it lays out roughly 3-up at typical panel widths and wraps to 2-up at narrow widths.

Pro lock

Inspecting binding data requires Corral Pro. When you’re not on Pro, the bindings region renders with the tile grids blurred to unreadability — section headers and counts stay sharp so you can still see the shape of your Worker. A single Pro · Inspect bindings ↗ pill sits centered over the region; tapping it opens the upgrade dialog.

Dependencies Tab

The Dependencies tab shows all packages declared in package.json with their version status.

Table Columns

• Status — icon indicating the dependency’s state:
  • Green checkmark: up to date
  • Arrow up: safe update available (within declared semver range)
  • Warning triangle: only a breaking (major) update available
• Package — dependency name with the declared semver range shown below (e.g., ^5.9.0)
• Installed — version currently in the lock file
• Wanted — highest published version matching the declared range
• Latest — highest published version overall
• Severity pill — “major”, “minor”, or “patch” badge on the Wanted and Latest columns when an update is available

Filtering and Sorting

Use the Show dropdown in the header to filter by:

• All — every dependency
• Safe Updates — only packages with a newer version within the declared range
• Outdated — any package where installed < latest
• Production / Development — filter by dependency type

Click the Package column header to sort alphabetically (ascending/descending).

Updating Dependencies

• Update All button (header) — appears when safe updates are available. Shows a confirmation dialog explaining what will happen, then runs the equivalent of npm update for the project’s package manager. Does not modify package.json.
• Update to Wanted (right-click context menu) — updates the selected packages within their declared semver ranges. No confirmation needed — this is always a safe operation.
• Update to Latest (right-click context menu) — updates the selected packages to the absolute latest version. Shows a confirmation warning that this may include breaking changes and will modify package.json.

A progress indicator appears in the header during updates. All update buttons are disabled while an update is in progress. After completion, the dependency list refreshes automatically.

Package Manager Support

Corral detects the package manager from lockfiles and uses the correct commands:

Manager	Lockfile	Update command	Install latest
npm	package-lock.json	npm update	npm install pkg@latest
yarn (Berry)	yarn.lock	yarn up	yarn add pkg@latest
yarn (v1)	yarn.lock	yarn upgrade	yarn add pkg@latest
pnpm	pnpm-lock.yaml	pnpm update	pnpm add pkg@latest
bun	bun.lock	bun update	bun add pkg@latest

Network Tab

The Network tab is Corral’s Browser & Network capture surface — a live, searchable timeline of the project’s HTTP access, browser console output, and page network activity.

• Origin filters — narrow to server access, browser console, or page network activity
• Per-tab selector + full-text search across the captured timeline
• Chronological event list — every event in context
• Event inspector — select an event to see its headers, body, and source-map-resolved stack frames (labeled by event kind)

Browser console output also folds into the Logs tab below. When you’re not on Pro, the tab shows the standard upgrade treatment. See Browser & Network for the full feature.

Logs Tab

A real-time log viewer for this project, rendered as styled text in a native text view.

• Source filter — show all entries or filter by origin (Corral, Process, Caddy, DNS)
• Stream filter — show all, stdout only, or stderr only
• Text filter — in the toolbar to narrow down entries
• Cmd+F find bar — native macOS find bar for searching within displayed text
• Auto-scroll toggle — when active (blue), the view follows new output; scrolling up disables it
• Font size — Cmd+Plus / Cmd+Minus / Cmd+0 to adjust
• Word wrap — toggle in the toolbar menu; when off, the view scrolls horizontally
• Clear button and Copy/Export in the toolbar menu
• Process stderr highlighted in red
• Text is fully selectable for copying (Cmd+C)
• Entry count and time range displayed in the status bar

Failure History Tab

The Failure History tab shows a chronological list of all failures this project has encountered, persisted to disk at ~/.corral/units/<id>/failures.jsonl. Each failure entry includes:

• Timestamp — when the failure occurred
• Failure kind — structured failure type (PortInUse, ReadinessTimeout, InsufficientDiskSpace, UpstreamFailure, etc.)
• Diagnostic message — human-readable explanation
• Trigger — whether this was a self-fault or a cascade failure triggered by an upstream dependency
• Log snapshot — a capture of the most recent ~100 log entries at the time of failure

Selecting a failure in the list shows its details in the right pane:

• Failure chain (for cascade failures) — a breadcrumb trail linking this failure back to its root cause, with navigation to the upstream unit
• Remediation actions — suggested next steps (Retry, View Logs, Check Upstream, etc.)
• Log snapshot viewer — inline log viewer showing the captured logs at failure time, with the same filtering and search features as the main Logs tab
• Snapshot picker — a dropdown to jump between different failure snapshots for comparison

The failure ledger is capped at 1000 entries and 10 MB per unit. Daemon startup truncates older entries if the cap is exceeded.

Settings Tab

Configure project-specific settings:

• Node.js version — pick from installed versions or use “Default” (shows the resolved version)
• Custom subdomain — override the auto-generated subdomain, with a live preview of the full domain ({subdomain}.{tld}). As you type, an anticipatory validation chip appears next to the field: clean (green checkmark) when the subdomain is valid and available, amber warning when a synchronous check detects an issue (subdomain taken, invalid format), or red error when an async dry-run probe fails (DNS down, proxy unreachable, disk space insufficient). The chip debounces as you type and auto-commits the change when it clears to clean.
• Wrangler environment — select from environments defined in your wrangler config, or “Default” for the top-level config (Cloudflare projects only)
• Auto-start — toggle whether this project starts with corral up
• Dev command — a field to set a custom command override. The effective command that will run is shown below the field. Use “Reset to default” to clear the override and revert to auto-detection.
• Open at — how the project is served: <name>.test (default — the proxy route), localhost (HTTP) (http://localhost:<port>), or localhost (HTTPS) (https://localhost:<port> and https://127.0.0.1:<port> via Corral’s locally-trusted CA — works even with global HTTPS off; the CA is trusted on demand). Pick a localhost mode for apps whose own code hard-codes a localhost assumption. See Serving a project at localhost.
• Localhost port — pin the front-door port for a localhost mode (chip-validated like the subdomain field), or leave it on Auto to let Corral pick a free one. An address-mode change applies on the project’s next start.
• Also serve <name>.test — when a localhost mode is selected, keep the .test route too (dual-home); turn it off to serve localhost only.
• Repository — shows the detected git remote URL (if any) with an Update button to re-detect from the current git configuration. Useful if the remote changes after the project was registered.
• Open in Browser / Editor / Terminal — per-project overrides of the app-wide Preferred Browser, Preferred Editor, and Preferred Terminal. Each defaults to Use app default (inherit the global setting). The launchers live on the project’s right-click menu and as keyboard shortcuts on the selected project — ⌘O (browser), ⇧⌘O (editor), ⌃⌘O (terminal); editor and terminal open the project root, the browser opens its URL.

Anticipatory validation surfaces issues at save time, before you apply a change. Two tiers:

• Tier-1 (sync, ≤50ms): port collisions, dependency cycles, subdomain format checks. Runs inline on every keystroke.
• Tier-2 (async, ≤500ms, cancellable): OS port probes via lsof, disk-space checks, DNS resolution tests. Runs on a debounce timer and can be cancelled if you keep typing.

The dry-run chip shows the validation state. A form-level chip above the settings catches failures no per-field filter claims (e.g., InsufficientDiskSpace).

Appearance

The Appearance section shows the project’s visual identity and lets you override it.

• Icon — preview of the resolved icon (44pt square). When the icon was auto-detected, a Using <path> hint shows where Corral found it (for example, Using public/favicon.ico). Click Choose Image… to pick a custom image (PNG, JPEG, SVG, ICO, WebP, or GIF). Custom icons are copied into Corral’s data directory, so deleting or moving the original from your project will not break the icon. Use Reset to remove the override and revert to the auto-detected icon.
• Color — backdrop color used behind the icon and as the avatar background when no icon is available. The picker reflects the manifest’s theme_color if one was found, otherwise a deterministic palette color hashed from the project name. Reset removes the override.

When neither a custom nor inferred icon exists, the catalog renders a one- or two-letter initials avatar instead.

Settings are saved automatically as you change them.

You can also remove the project from Corral at the bottom of this tab.

Binding Browsers

Binding browsers open as sheets (modal overlays) from the Overview tab. All browsers use a split-view layout with a list on the left and a detail view on the right.

D1 Browser

• Left pane: table list with row counts
• Right pane: paginated row viewer with column headers (50 rows per page)
• Navigate pages with Previous/Next controls showing “Rows X–Y of Z”
• Right-click a table for Show Schema (columns, types, constraints)
• Reset Local Data (destructive) — truncates every user table in place; the schema and .sqlite file are preserved

KV Browser

• Left pane: key list with a prefix search filter
• Right pane: key detail showing the value (monospaced), expiration, and metadata
• Right-click a key for Delete, or Edit TTL to set or clear its expiration

R2 Browser

• Left pane: object list with prefix search, showing key and formatted size (B/KB/MB)
• Right pane: object detail with key, size, and ETag
• Right-click an object for Delete — removes the object and its data blob

Durable Objects Browser

• Left pane: instance list with IDs and storage sizes
• Right pane: paginated storage entries (key-value pairs) for the selected instance
• Right-click an instance for Reveal in Finder — opens its .sqlite file in Finder

Secrets Store Browser

• Left pane: paginated list of secret names
• Right pane: secret detail with name, ID, and masked value
• Click the eye icon to reveal the value (masked with bullets by default)
• Add Secret button (+) in the toolbar — opens a form for name and value
• Delete button (trash icon) with a confirmation dialog

Workflows Browser

• Left pane: instance list with IDs, statuses (Created/Running/Completed), and step counts
• Right pane: instance detail showing params, trigger source, and ordered step list with type (Do/Sleep), status, config, and result
• Right-click a step for View Full Result — opens the step’s complete result JSON in a pop-out viewer