Documentation
Everything you need to install, build, and contribute to Land.
Get Started in Minutes
The README walks you through installation, first build, and the fifteen-element architecture. No prior Rust or Tauri knowledge required.
Report a Bug or Request a Feature
Open an issue on GitHub. The team monitors daily and labels good-first-issue tasks for new contributors.
Rust API Reference
Browse generated rustdoc output for Mountain, Echo, Air, and 11 more Rust crates.
Start
Introduction
What Land is, what FIDDEE is, what is working today, what is not yet complete, and the architectural philosophy behind replacing the VS Code backend with Rust, Tauri, and Effect-TS.
Installation
System requirements, submodule clone instructions, build profiles, artifact paths, macOS code signing, and environment setup for building Land from source.
Project Structure
The Element monorepo layout - each element's role, naming conventions, build system, and critical rules about what must never be edited.
Guide
Getting Started
Step-by-step build instructions for the Land code editor from source, covering prerequisites, environment setup, VS Code platform compilation, Land application assembly, and troubleshooting.
Quickstart
Concise build reference for Land from source - prerequisites, two-step build flow, common profiles, and development environment setup.
Configuration
Complete reference for Land's multi-file environment variable system — file hierarchy, sourcing cascade, variable domains, tier-gating feature mapping, consumer mapping, and usage examples.
CI/CD Pipeline
Complete build pipeline for the Land code editor - stages from environment variable resolution through binary artifact production, profile system, artifact layout, and automation details.
Inter-Component Protocol
Specifies the communication protocols used between Land components: gRPC service definitions (Vine protocol), Tauri IPC mechanism, Spine extension coordination protocol, and connection lifecycle management.
Elements
Air
Air is the persistent background daemon that offloads update management, file indexing, cryptographic operations, and health monitoring from the main editor process.
Cocoon
The Node.js extension host sidecar for Land. Runs VS Code extensions unmodified in a supervised Node.js process, constructs a per-extension vscode API shim via Effect-TS layers, and communicates with Mountain over the Vine gRPC protocol for native operations.
VS Code Source Validation Checklist for Cocoon
Validates Cocoon's implementation against the original VS Code source to ensure compatibility and correctness. Covers extension host architecture, API compatibility, and communication patterns.
Common
Common defines the abstract architectural contracts for the entire Rust backend: the ActionEffect system, async service traits, DTOs, and the universal CommonError type.
Echo
Echo is the work-stealing task scheduler embedded in Mountain, providing priority-aware concurrent execution for background work without competing with the Node.js extension host.
Grove
Grove is the native Rust and WebAssembly extension host for Land, using Wasmtime to sandbox extensions with capability-based security instead of relying on Node.js process isolation.
Maintain
Maintain is the build orchestrator for Land, providing shell scripts for debug and release builds, GritQL queries for automated refactoring, and a turbo.json task graph - it does not need to be recompiled when changed.
Mist
Mist is a local DNS isolation server that intercepts all DNS queries for the editor.land zone, resolving private subdomains to loopback and blocking external access by allowlist.
Mountain
The Rust + Tauri native backend for Land: IPC dispatcher, Vine gRPC server, Environment providers, and Cocoon process orchestration.
Output
The build artifact management layer for Land that compiles VS Code platform source through a dual-compiler pipeline (ESBuild primary, Rest OXC optional), produces the @codeeditorland/output npm package, and is consumed by Cocoon, Sky, and Wind.
Rest
Rest is a high-performance TypeScript compiler built on the OXC (Oxidation Compiler) toolchain. It replaces esbuild's TypeScript loader with a Rust-powered OXC pipeline, producing VS Code-compatible output at 2-3x speed improvement.
Sky: UI Component Layer
Sky is the UI component layer of Land - the Astro-based interface that renders the editor, side bar, activity bar, status bar, and panels inside the Tauri WebView, loading the VS Code workbench from Output.
SideCar
SideCar manages the vendored Node.js runtime binaries that Land ships per platform, selecting the correct binary at compile time for each of four target triples so Cocoon always starts with the right runtime.
Vine
Vine defines the gRPC protocol between Mountain and Cocoon, providing strongly-typed inter-process communication contracts compiled from Protocol Buffer definitions.
Wind: Frontend Service Layer
Wind is the Effect-TS service layer for the VS Code workbench, enabling it to function inside a Tauri WebView by recreating the essential VS Code renderer environment through typed error and dependency injection patterns.
Worker
The Service Worker element for the Land editor. Implements multi-tier asset caching (network-first for app shell, cache-first for static assets) and a two-phase CSS import interception protocol that lets the VS Code workbench use standard import syntax inside the Tauri WebView.
Deep Dive
Air - Deep Dive
Technical architecture of the Air background daemon: gRPC service definitions, update pipeline, authentication, indexing, and connection lifecycle with Mountain.
Cocoon - Deep Dive
Internals of the Cocoon extension host: core architecture principles, 7-stage bootstrap ordering, Effect-TS usage patterns, RequireInterceptor rules, gRPC server implementation, extension activation lifecycle with topological ordering and cycle guard, dual-track TierIPC routing, and the showInformationMessage call path end-to-end.
Common - Deep Dive & Architecture
Technical foundation of the Common crate: ActionEffect system, trait-based dependency injection, DTO library, CommonError variants, VSCode service lifting patterns, and performance characteristics.
Architecture
The complete system architecture of the Land code editor - process model, inter-component communication patterns, component responsibilities, and the layered design that enables multi-process operation on macOS, Windows, and Linux.
Echo - Deep Dive & Architecture
Deep dive into Echo, the work-stealing scheduler that provides efficient task execution for Mountain's ApplicationRunTime and other components requiring asynchronous task management.
Grove - Deep Dive
Deep dive into Grove, the native, sandboxed Rust/WASM extension host that provides an environment for running VS Code extensions compiled to WebAssembly or native Rust, complementing the Node.js-based Cocoon host.
Maintain - Deep Dive
Architecture overview of the Maintain build orchestrator: Rust binary and library, Rhai scripting engine, TOML/JSON5 config editing, data flow, integration points, and CLI configuration.
Mountain - Deep Dive & Architecture
Technical foundation for implementing VSCode services as native Rust services within the Land project. Covers the concrete implementation layer that brings VSCode service compatibility through native Rust implementations, Tauri integration, gRPC communication, process management, encryption, and performance optimization.
Rest - Deep Dive
Rest TypeScript compiler architecture, OXC toolchain pipeline, key modules, data flow, integration points with Output/Cocoon/Sky, and configuration reference.
SideCar - Deep Dive
Platform triple detection, binary resolution cascade, download integrity verification, cache directory structure, Mountain ProcessManagement integration, and version mismatch handling.
Sky - Deep Dive
Architecture, key modules, Sky Bridge event routing, build optimization, data flow, integration points, and configuration for the Sky UI component layer in the Land project.
Vine - Deep Dive
Vine gRPC protocol layer - technical foundation for strongly-typed inter-process communication between Mountain, Cocoon, and Air. Proto file structure, MountainService and CocoonService RPC definitions, bidirectional streaming patterns, build.rs compilation, URI/Range message formats, and how new RPCs are added.
Wind - Deep Dive
TauriLiveLayer construction, full TierIPC routing table with per-subsystem overrides, Layer.succeed service composition, eager ManagedRuntime singleton, Preload.ts global shimming, Generated Upstream import depth, the Wind Codegen pipeline, core architecture principles, service implementation patterns, and security architecture.
Mist - Deep Dive
Mist DNS isolation layer - local authoritative DNS server for the editor.land zone, Hickory DNS architecture, forward allowlist enforcement, DNSSEC zone signing, and resolver construction for consumer integration.
Worker - Deep Dive
Worker registration pattern, fetch interception message protocol, ESBuild bundle configuration, and service worker lifecycle stages.
Workflows
Application Startup and Handshake
How Mountain, Cocoon, and the Wind workbench initialise and establish their IPC connections on every launch.
Opening a File from the UI
How a file-tree click travels from Sky through Wind's editor and filesystem services to a Mountain disk read, then back to Monaco.
Invoking a Language Feature Hover Provider
How a user hover in Monaco triggers a round-trip through Wind, Mountain IPC, a Cocoon gRPC call to the registered extension provider, and back.
Saving a File with Save Participants
How Ctrl+S triggers save participants in Cocoon before Mountain writes the final formatted content to disk.
Executing a Command from the Command Palette
How Ctrl+Shift+P fetches the command list from Mountain and routes execution to either a native Rust handler or a proxied Cocoon extension command.
Creating and Interacting with a Webview Panel
How an extension creates a native webview panel via Cocoon and Mountain, sets HTML content, and exchanges messages with the host.
Creating and Interacting with an Integrated Terminal
How Mountain spawns a native PTY, streams output to Sky via Tauri events, and routes keystrokes back to the shell process.
Source Control Management (SCM)
How the built-in Git extension registers an SCM provider in Cocoon, uses Mountain to run native git commands, and keeps the SCM view in Sky up to date.
User Data Synchronization
How settings, keybindings, and extension state are persisted via Mountain storage and optionally synchronised across sessions.
Running Extension Tests
How the Extension Development Host model spawns a second isolated Mountain+Cocoon pair and lets the test runner remote-control the main editor window.
Tier-Gated Implementation Selection
How .env.Land propagates through build tools into Mountain, Cocoon, Wind, and Sky, selecting which implementation tier each capability runs on.
Why Land
Why Rust
Mountain, Land's native backend, is written in Rust because the operations an editor performs most frequently - file I/O, terminal management, OS dialogs, and keychain access - are exactly where a GC-pausing runtime pays the highest penalty.
Why Tauri
Tauri gives Land a native desktop shell without bundling Chromium - the system WebView renders the UI while a Rust backend owns every OS interaction.
Why Effect-TS
Effect-TS gives Cocoon and Wind typed error channels, fiber-based structured concurrency, and compile-time dependency injection - the three things a VS Code extension host cannot safely build on raw Promises.
Why gRPC
Vine.proto is the single source of truth for Mountain-Cocoon communication - one schema generates typed Rust stubs via tonic and TypeScript stubs via proto-loader, with bidirectional streaming for real-time events.
Why WebAssembly
Grove uses Wasmtime to run extensions inside a capability-bounded WASM sandbox - the same binary runs on macOS, Linux, and Windows with no Node.js dependency and with OS access granted explicitly rather than by default.
Why CC0
Land uses CC0 1.0 Universal - a public domain dedication with no attribution requirement, no conditions, and no patent clauses - because infrastructure for developers should have zero legal friction to use, fork, or embed.
Reference
Filesystem Footprint
Every host-filesystem location the editor reads or writes, mapped to its producing code, with cross-platform resolution and cleanup recipes.
Filesystem Footprint — User Dotfile
The ~/.fiddee/ tree — Land's primary product-owned filesystem domain, cross-OS resolution, sub-directory map, and Cocoon-side mirror.
Filesystem Footprint — Platform Paths
OS-specific resolution for every per-bundle, OS-managed, and temp-directory path Land touches on macOS, Linux, and Windows.
Filesystem Footprint — Per-Element Write Sites
Every Land Element grouped by which filesystem location it touches — the reverse map of UserDotfile and PlatformPaths.
Filesystem Footprint — Environment Variables
Every env var that shapes a filesystem path, controls log volume, or affects the bundle identifier — grouped by role.
Filesystem Footprint — Cleanup Recipes
Per-OS commands to wipe every piece of Land / FIDDEE state from a system, plus the archive pattern used in production cleanups.
Filesystem Footprint — Encapsulation Directions
Potential refactors that would shrink Land's filesystem footprint, simplify cleanup, or unblock versioning.
Build Pipeline
The complete build pipeline for the Land code editor, from environment variable resolution through binary artifact production — six stages across Rust, TypeScript, and static asset compilation.
Build Matrix
Every build configuration variant, environment variable, and how they propagate across all Elements in the Land monorepo.
Polyfills and Compatibility Shims
Every polyfill, shim, and compatibility layer that enables the VS Code workbench and extension host to function inside Land's Tauri WebView and Node.js sidecar architecture.
Workflow Overview
High-level overview of Land's architecture and the core workflows that drive the application — from startup and file I/O to extension execution and SCM integration.
Development
Contributing
How to contribute bug reports, pull requests, documentation, and extension compatibility reports to the Land code editor project, including code style, commit conventions, and security reporting.
Extension Development
How to develop, test, and report compatibility issues for VS Code extensions running in Land.
Dependency Management
How to manage JavaScript and Rust dependencies in the Land monorepo, including pnpm workspace protocol, Cargo patch redirects, and submodule updates.
Mountain Naming Conventions
Documents Mountain's PascalCase naming convention for Rust elements, explaining the cross-language DTO alignment with TypeScript and gRPC Protocol Buffers.
Development History
Key architectural decisions in Land's development and the reasoning behind each one.
Local-First Protocol
Land's local-first design philosophy: how editor state, extension data, and file operations stay on-device without requiring cloud services.
Troubleshooting
Common build, startup, and runtime issues with Land and how to resolve them.
VS Code API Coverage Matrix
Authoritative map of every top-level vscode.* API surface and its implementation split across Sky (workbench renderer), Cocoon (extension-host Node sidecar), and Mountain (Rust backend). Drives the dual-track strategy.
Effect-TS + OpenTelemetry - Integration Pattern
Describes how Wind and Cocoon use Effect's first-class OpenTelemetry support through @effect/opentelemetry, exporting to both an OTLP collector and PostHog events via custom SpanProcessors.
Land Telemetry - Overview
Overview of Land's telemetry architecture using two parallel pipes - logs and traces - that share a single trace_id for correlation.
Sidecar Telemetry
Documents how every Rust sidecar (Air, Echo, Rest, Grove, Mist, SideCar, Worker) and the Worker service worker emit telemetry through the same land:<tier>:* namespace and stamp $tier for dashboard pivoting.
Production Zero - Tree-Shaking Telemetry
Contract specifying that a cargo build --release of any Rust element and an astro build of Sky must contain zero bytes of telemetry SDK code, no PostHog endpoint string, and no feature flag SDK code.
Low-Level Shim
Coverage
How Land Replaces VS Code's Electron Stack
VS Code runs on Electron: a Chromium browser, a Node.js runtime, and an extension-host model. Land replaces those pieces with independent elements while preserving the VS Code extension API as the compatibility target. Browse individual elements in the Element section above, or explore the workspace on GitHub.
Backend Services
Four Cloudflare Workers power the Land backend infrastructure:
- Auth↗ - OAuth 2.0, JWT session tokens, and Auth0 integration
- Download↗ - Binary distribution, release metadata, and update checks
- Status↗ - Health checks and uptime monitoring
- Analytics↗ - Privacy-first usage telemetry routed through Cloudflare Analytics Engine
Live Deployments
Public website and documentation surfaces are deployed separately from the local editor runtime:
Marketing website (Cloudflare Pages)
Status ↗Uptime dashboard (Cloudflare Pages)
Rust API: Mountain ↗rustdoc for Mountain, Echo, Common, Air, SideCar
Rust API: Rest ↗rustdoc for OXC-powered TypeScript compiler
Rust API: Maintain ↗rustdoc for build orchestrator
Rust API: Common ↗rustdoc for abstract traits and DTOs
Rust API: Echo ↗rustdoc for work-stealing scheduler
Rust API: Air ↗rustdoc for background daemon
Rust API: SideCar ↗rustdoc for Node.js binary distribution
Rust API: Land (Workspace) ↗rustdoc for the top-level workspace
Knowledge Base ↗Architecture knowledge graph (Cloudflare Pages)
Rust API (Interactive) →Browse all rustdoc sites with embedded iframes