Configuration

Land uses a multi-file .env system with 18 files across 6 domains. Environment variables control which implementation variants (tiers) are compiled into Mountain and activated at runtime by Cocoon, Wind, Sky, and Output.

Naming Convention

• Single-word PascalCase verbs (e.g., ProductVersion, TierFileSystem, Capture)
• No LAND_ prefix — variables are named for what they do, not where they come from
• One variable per line, KEY=value format, shell-sourced by TierEnvironment.sh

File Hierarchy

There are 18 environment files across 6 domains:

Core (.env.Land)

Node (.env.Land.Node)

Extensions (.env.Land.Extensions)

PostHog (.env.Land.PostHog)

Diagnostics (.env.Land.Diagnostics)

Bundled (.env.Land.Bundled)

Sourcing Cascade

The sourcing cascade is orchestrated by Maintain/Script/TierEnvironment.sh. Each file is source-ed in order, so later files override earlier ones for the same key.

Sourcing Order

Step  +------------------------------+
  1   | .env.Land                    |  Core dev defaults
      | +-- fallback: .env.Land.Sample|  (used if dev file absent)
  2   | .env.Land.Production         |  Core prod overlay (if NODE_ENV=production or Profile contains "release")
  3   | .env.Land.Node               |  Node runtime dev defaults
      | +-- fallback: .env.Land.Node.Sample
  4   | .env.Land.Production.Node    |  Node runtime prod overlay
  5   | .env.Land.Extensions         |  Extension dirs dev defaults
      | +-- fallback: .env.Land.Extensions.Sample
  6   | .env.Land.Production.Extensions| Extension dirs prod overlay
  7   | .env.Land.PostHog            |  PostHog/OTLP dev defaults
      | +-- fallback: .env.Land.PostHog.Sample
  8   | .env.Land.Production.PostHog |  PostHog/OTLP prod overlay
  9   | .env.Land.Diagnostics        |  Debug knobs dev defaults
      | +-- fallback: .env.Land.Diagnostics.Sample
 10   | .env.Land.Production.Diagnostics| Debug knobs prod overlay
 11   | .env.Land.Bundled            |  Bundle layout dev defaults
      | +-- fallback: .env.Land.Bundled.Sample
 12   | .env.Land.Production.Bundled |  Bundle layout prod overlay
      +------------------------------+

Key Rules

1. Overlay conditional — Production overlays are only sourced when NODE_ENV=production or the Profile variable contains the substring release. For all development profiles, only the dev files (steps 1, 3, 5, 7, 9, 11) are loaded.

2. Fallback chain — If a dev file (e.g., .env.Land) is absent or empty, the corresponding .Sample file is sourced as a fallback.

3. Last-write-wins — Since all files are shell-sourced into the same environment, identical keys in later files silently override earlier values. For example, Trace=all in .env.Land.PostHog is overridden by Trace= (empty) in .env.Land.Production.PostHog.

4. Absent files skipped — Files that do not exist on disk are silently skipped. No error is raised.

5. Build-time vs runtime — Variables set during the sourcing cascade are available at:

   • Build time — Read by Mountain/build.rs for cargo:rustc-env, cargo:rustc-cfg, and esbuild/Vite define substitutions.
   • Runtime — Read by Mountain (Rust std::env::var), Cocoon (esbuild constants), Wind (import.meta.env), and Sky (__LandTiers/__LandProduct).

Variables by Domain

Core

Node

Extensions

PostHog (Telemetry)

OTLP (OpenTelemetry)

Diagnostics

Bundled

Build-Shim

These variables are not stored in .env files. They are exported by Build.sh during the build process and consumed by various consumers.

Tier-Gating Feature Mapping

Tier values from .env.Land are translated by TierEnvironment.sh into Cargo feature flags passed to Mountain’s build.rs. The mapping is as follows:

Notes

• Default values do not activate features. The Cargo features listed above are only enabled when the variable is explicitly set to the non-default value. For example, TierFileSystem=Layer2 (the default) does not activate any feature; only TierFileSystem=Layer4 activates TierFileSystemLayer4.
• Layer3 and Layer5 values (e.g., TierClipboard=Layer3, TierFileSystem=Layer3) are implementation choices embedded in Mountain’s code paths but do not correspond to Cargo features in the current mapping.
• Tier values without feature mappings (TierDocumentMirror, TierExtensionActivation, TierModuleCache, TierTelemetry) are read at runtime via std::env::var and influence behavior without requiring a compile-time feature gate.

Consumer Mapping

This table shows which Elements read which variables and through what mechanism.

How Each Element Consumes Variables

localStorage Runtime Overrides

The following variables can be toggled at runtime via the browser DevTools console:

// Disable all Land shims/polyfills/connections
localStorage.setItem("Disable", "1");

// Enable boot-time smoke harness
localStorage.setItem("Smoke", "1");

Changes take effect on the next application cycle. A restart may be required for some gates.

Usage Examples

Overriding for Parallel Development Sessions

If you need to run multiple Land instances side-by-side with different tier configurations, edit the .Sample file and point specific sessions at it:

# Session 1: Default dev (reads .env.Land)
cd /Volumes/CORSAIR/Developer/macOS/Application/CodeEditorLand
cargo build -p mountain

# Session 2: Experimental layers
# Temporarily swap .env.Land with a custom file
cp .env.Land .env.Land.backup
cat > .env.Land << 'EOF'
TierFileSystem=Layer4
TierFindFiles=Layer4
TierFileWatcher=Layer4
EOF
cargo build -p mountain

# Restore original
mv .env.Land.backup .env.Land

Alternatively, use the .Sample file as a clean baseline for experiments:

# Keep your main .env.Land unchanged, experiment with Sample
cp .env.Land.Sample .env.Land.Experimental
# Edit .env.Land.Experimental with your changes
# The sourcing cascade will fall through to .Sample if no dev file exists

Enabling Telemetry Debugging

# In .env.Land.PostHog:
Authorize=phc_your_key_here
Beam=https://eu.i.posthog.com
Report=true
Capture=true
Trace=all
OTLPEndpoint=http://127.0.0.1:4318
OTLPEnabled=true
Record=1

Then run a local Jaeger instance:

docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4318:4318 \
  jaegertracing/all-in-one:latest

• Record=1 mirrors PostHog batches and OTLP payloads to NDJSON files at <app-data>/logs/<timestamp>/. Useful for offline inspection.
• Trace=all captures spans for all elements. Narrow it down with Trace=mountain,cocoon to reduce noise.

Using localStorage to Flip Gates at Runtime

No restart required for these gates — toggle them in the DevTools console:

// Enable boot-time smoke test harness
localStorage.setItem("Smoke", "1");

// Disable all Land customizations (shims, polyfills, connections)
localStorage.setItem("Disable", "1");

To revert:

// Clear the override (or set to "0"/"false")
localStorage.removeItem("Smoke");
localStorage.removeItem("Disable");

Disabling All Land Customizations for Bisecting

When bisecting a regression, you may need to run with all Land-specific shims, polyfills, and connections disabled:

Method 1: .env.Land.Diagnostics file

# In .env.Land.Diagnostics or .env.Land.Diagnostics.Sample:
Disable=true

Method 2: localStorage (runtime only)

localStorage.setItem("Disable", "1");

When Disable=true:

• All Output transforms are dropped
• Cocoon and Air spawn are skipped
• CloseRequested intercept is disabled
• SkyBridge is not installed
• The application falls back to vanilla VS Code behavior

This is ideal for git bisect to determine whether a regression originates in Land’s customization layer or upstream VS Code.

Switching Extension Loading Modes

# Load only user extensions, skip all built-ins
Skip=true

# Completely mute all extensions (no extension host)
Mute=true

# Load development extensions from a custom path
Probe=/path/to/my-extension

# Add additional extension directories (colon-separated)
Extend=/opt/custom-extensions:/home/user/more-extensions

Building for Production

The production overlay chain is triggered automatically:

export NODE_ENV=production
# or
export Profile=release-electron-bundled

This causes TierEnvironment.sh to source all .env.Land.Production.* overlays after their dev counterparts. Key differences:

Debugging Cocoon’s Node.js Version

# Force a specific Node.js binary
Pick=/opt/homebrew/opt/node@22/bin/node

# Check your current Node.js version (must be >= Require value)
node --version

# Change the minimum required version
Require=22

If Cocoon detects a version below Require, it will fail to spawn with a version mismatch error.

Enabling Persistent Mountain Logging

# In .env.Land.Diagnostics:
Record=1

Mountain’s dev log will be written to:

<app-data>/logs/<timestamp>/Mountain.dev.log

This is separate from the standard application log and includes all tagged output (if Trace is also set).

Appendices

A. Common Trace Tags

When Trace is set (in either PostHog or Diagnostics domain), these are the most common tag values:

Combine tags: Trace=lifecycle,ipc,extensions,grpc

B. File Paths Summary