Air 🪁

The Native Background Daemon for Land 🏞️

VS Code cold-starts slowly because everything initializes fresh each launch. Updates require a full restart that kills open terminals and in-progress work. There is no mechanism to pre-stage work between sessions.

"The next version is already downloaded and verified before you decide to update. The main window never blocks waiting for a download."

Both badges moved off the /badge/ path, whose single-string slugs (License-CC0_1.0-lightgrey.svg and Rust-1.95.0+-orange.svg) break as soon as a label or message contains a slash. The superseded markup is kept here for provenance:

README.md (superseded badge markup)

[![License: CC0-1.0](https://img.shields.io/badge/License-CC0_1.0-lightgrey.svg)](https://github.com/CodeEditorLand/Air/tree/Current/LICENSE)
[![Rust Version](https://img.shields.io/badge/Rust-1.95.0+-orange.svg)](https://www.rust-lang.org/)

Note

Same two badges, same meaning - only the endpoint changed, with + encoded as %2F-style percent escaping (%2B) so the message survives the URL.

Rust API Documentation 📖

Overview

Air is the lightweight, persistent daemon that powers the background capabilities of the Land Code Editor. While Mountain ⛰️ handles the core application logic and UI, Air operates as a specialized sidecar process dedicated to heavy lifting, network operations, and system maintenance. It ensures that the main editor remains responsive by offloading resource-intensive tasks such as updates, large downloads, cryptographic signing, and file indexing.

VS Code cold-starts slowly because everything initializes fresh each launch, and updates require a full restart. Air solves this by running as a persistent background process that survives window closures, pre-stages updates, and keeps a warm file index across sessions - so the editor is always ready the moment you launch it.

Air is engineered to:

Serve as the Persistent Background Daemon - Run as a standalone process alongside Mountain ⛰️, surviving window closures and maintaining background services across sessions via Daemon/ singleton enforcement and platform-native daemonization.
Own the Update Lifecycle - Take full ownership of downloading, verifying, and applying patches for Land without user interruption or restart prompts, with staged installation and automatic rollback via Updates/.
Offload Heavy Network Operations - Act as the traffic manager for large downloads (extensions, language servers, dependencies) with resilient, resume-capable transfers through Downloader/ and Resilience/.
Isolate Security-Critical Operations - Manage cryptographic signing, secure credential storage, and authentication token lifecycle via Security/ and Authentication/, keeping sensitive logic isolated from the main application process.

Key Features 🪁

gRPC Native Communication - All inter-process communication with Mountain ⛰️ travels over a Vine 🌿 (tonic-based gRPC) channel on [::1]:50053, providing strongly-typed protobuf contracts, bi-directional streaming for progress events, and a well-defined API surface generated from Proto/Air.proto.

Self-Contained Daemon Lifecycle - Runs as an independent process with singleton enforcement via PID locking in Daemon/, graceful shutdown on SIGTERM managed by Binary/Shutdown/WaitForShutdownSignal.rs, and platform-native daemonization on macOS, Linux, and Windows. Survives window closures and persists across editor sessions.

Resilient Update Engine - Full ownership of the update lifecycle: version checking against multiple channels (stable, beta, nightly) in Updates/, concurrent chunked downloads with resume capability in Downloader/, cryptographic checksum verification via Security/ChecksumVerifier.rs, staged installation, and automatic rollback on failure via Updates/RollbackState.rs.

Isolated Security Boundaries - Cryptographic signing with ring, AEAD encrypted credential storage with zeroize in Security/SecureStorage.rs, token lifecycle management in Authentication/, rate limiting via token bucket in Security/TokenBucket.rs, and a comprehensive security audit subsystem in Security/SecurityAuditor.rs - all isolated from the main application process.

Real-Time File Indexing - Persistent file index with Rust and TypeScript symbol extraction in Indexing/Language/, recursive directory scanning via Indexing/Scan/, notify-based file system watching for live updates in Indexing/Watch/, and a fast query engine with fuzzy search across the entire workspace in Indexing/Store/.

Observability by Default - Structured JSON logging with trace-ID propagation in Logging/, OpenTelemetry-compatible distributed tracing with configurable sampling in Tracing/, and Prometheus-compatible metrics for latency, success rates, and resource utilization across every service in Metrics/.

Resilience Everywhere - All network operations are wrapped in retry-with- exponential-backoff via Resilience/Retry.rs, circuit breakers with half-open probing in Resilience/CircuitBreaker.rs, bulkhead executors for service isolation in Resilience/BulkheadExecutor.rs, and configurable timeouts via Resilience/Timeout.rs.

Core Architecture Principles 🏗️

Principle	Description	Key Components
Sidecar Isolation	Run as a standalone daemon process, surviving independently of the main window lifecycle for persistent background operations.	`Daemon/`, `Binary/`, PID locking
`gRPC` IPC Boundary	Use Vine 🌿 (`tonic`-based `gRPC`) for all communication with Mountain ⛰️, ensuring a high-performance and well-defined API.	`Vine/`, `Proto/Air.proto`, generated `prost` bindings
Service Modularity	Each capability (updates, downloads, auth, indexing) lives in its own module with independent startup and health monitoring.	`Updates/`, `Downloader/`, `Authentication/`, `Indexing/`
Resilience by Default	Wrap all network operations in retry-with-backoff, circuit breakers, bulkheads, and timeouts via the shared `Resilience/` library.	`Resilience/`, `HealthCheck/`
Secure Credential Handling	Never expose raw secrets; store credentials with AEAD encryption (`ring`), enforce key rotation, and audit all access.	`Security/`, `Authentication/`, `zeroize`

System Architecture

graph LR
    classDef mountain fill:#f0d0ff,stroke:#9b59b6,stroke-width:2px,color:#2c0050;
    classDef air      fill:#e0f4ff,stroke:#2471a3,stroke-width:2px,color:#001040;
    classDef external fill:#ebebeb,stroke:#888,stroke-width:1px,stroke-dasharray:5 5,color:#333;
    classDef infra    fill:#fff3c0,stroke:#f39c12,stroke-width:1px,stroke-dasharray:5 5,color:#5a3e00;

    subgraph MOUNTAIN["Mountain ⛰️ - Main Application"]
        MountainIPC["Mountain gRPC client delegates heavy tasks"]:::mountain
    end

    subgraph AIR["Air 🪁 - Persistent Background Daemon (::1:50053)"]
        direction TB
        subgraph COMM["Vine/ - gRPC Transport"]
            VineServer["Vine/Server/ - gRPC server (Generated/ prost bindings)"]:::air
            MountainClient["Mountain gRPC client (Air → Mountain callbacks)"]:::air
        end
        subgraph CORE["Core Services"]
            Updates["Updates/ - version check, download, verify, staged install, rollback"]:::air
            Downloader["Downloader/ - parallel chunks, rate-limit, resume, retry"]:::air
            Auth["Authentication/ - token mgmt, AEAD encrypt, key rotation"]:::air
            Indexing["Indexing/ - file index, symbol extract, FS watch, search"]:::air
        end
        subgraph INFRA["Infrastructure"]
            Health["HealthCheck/ - Alive/Responsive/Functional, auto-recovery"]:::infra
            Resilience["Resilience/ - retry backoff, circuit breaker, bulkhead"]:::infra
            Metrics["Metrics/ - Prometheus-compatible, latency, success rate"]:::infra
            Security["Security/ - AES-GCM, checksum, audit"]:::infra
            Daemon["Daemon/ - PID lock, singleton enforce"]:::air
        end

        VineServer --> Updates
        VineServer --> Downloader
        VineServer --> Auth
        VineServer --> Indexing
        Updates --> Resilience
        Downloader --> Resilience
    end

    subgraph EXTERNAL["External ☁️"]
        UpdateSrv["Update servers / extension registry"]:::external
    end

    MountainIPC -- gRPC :50053 --> VineServer
    MountainClient -- progress events --> MountainIPC
    Updates -- fetches --> UpdateSrv
    Downloader -- downloads --> UpdateSrv

Connection paths:

Path	Protocol	Use Case
Mountain ⛰️ → Air 🪁 via `gRPC`	`protobuf` over `gRPC` on port 50053	Delegate updates, downloads, indexing, auth
Air 🪁 → Mountain ⛰️ via `gRPC` callback	`protobuf` over `gRPC`	Progress events, health status, metrics
Air 🪁 → External via `HTTP`	`HTTPS` with `Mist` 🌫️ DNS isolation	Update servers, extension registries

Key Components

Component	Path	Description
Binary Entry Point	`Source/Binary.rs`	Binary entry point for the Air daemon
Library Root	`Source/Library.rs`	Module declarations and crate-level exports
Daemon Lifecycle	`Source/Binary/`	Daemon process lifecycle (startup, shutdown, monitoring)
Singleton Enforcer	`Source/Daemon/`	Singleton enforcement, PID locking, platform-native integration
Initialization	`Source/Initialize/`	Configuration, port binding, `gRPC` server construction, per-service startup
CLI Interface	`Source/CLI/`	Command-line interface for daemon interaction and diagnostics
`gRPC` Client	`Source/Client/`	Typed `gRPC` client (`AirClient`) and service provider (`AirServiceProvider`) for Mountain ⛰️ interaction
`gRPC` Protocol	`Source/Vine/`	`gRPC` protocol implementation (generated `prost` bindings, server, errors)
Application State	`Source/ApplicationState/`	Central coordination (connections, service states, telemetry, resources)
Configuration	`Source/Configuration/`	`TOML` config loading with schema validation, env overrides, hot reload
Updates	`Source/Updates/`	Version checking, download, verification, staged install, rollback
Downloader	`Source/Downloader/`	Parallel downloads, chunk transfers, rate limiting, resume capability
Authentication	`Source/Authentication/`	Token management, credential storage, AEAD encryption, key rotation
Indexing Engine	`Source/Indexing/`	File index, symbol extraction, scanning, persistent storage, FS watch
Health Check	`Source/HealthCheck/`	Multi-level health monitoring (alive, responsive, functional) with auto-recovery
Logging	`Source/Logging/`	Structured `JSON` logging with trace-ID propagation, rotation, sensitive data filtering
Metrics	`Source/Metrics/`	`Prometheus`-compatible metrics (latency, success rate, resource usage)
Resilience	`Source/Resilience/`	Retry with exponential backoff, circuit breaker, bulkhead, timeout management
Security	`Source/Security/`	Checksum verification, AES-GCM credential storage, rate limiting, audit subsystem
Tracing	`Source/Tracing/`	Distributed tracing with sampling, span events, context propagation
HTTP Client	`Source/HTTP/`	Secure HTTP client with custom DNS via `Mist` 🌫️, `TLS`, timeout management
Mountain Bridge	`Source/Mountain/`	Client for Mountain ⛰️ callbacks with `TLS` configuration
Plugin System	`Source/Plugins/`	Plugin discovery, loading, sandboxing, event bus, and capability management

Startup Configuration ⚙️

Source/Initialize/Configure/ is the pre-service step: it prepares the two things every later subsystem assumes are already settled - where logs go, and which address the gRPC server binds. It holds exactly two submodules, Log/ and Port/.

Unit	Entry point	Responsibility
`Initialize/Configure/Log/`	`ConfigureLog()`	Installs the `tracing` subscriber before any service emits a span
`Initialize/Configure/Port/`	`SelectPort()`, `ValidatePort()`	Parses and validates the bind address, rejecting the port Cocoon owns

Source/Initialize/Configure/Port/SelectPort.rs

pub fn SelectPort(bind_address:Option<String>) -> Result<SocketAddr, String> {
pub fn ValidatePort(port:u16) -> Result<(), String> {

Note

SelectPort defaults to [::1]:50053 and guards against the 50052/50053 conflict, so a misconfigured daemon fails at startup rather than mid-session.

Development Logging 🔍

Source/DevLog.rs is a tag-filtered development logger driven by the Trace environment variable. It is silent by default - an unset Trace produces no output at all, which is what keeps a background daemon quiet. The same tag vocabulary works across Mountain ⛰️, Air 🪁, and the TypeScript side, and Trace=short additionally aliases long app-data paths to $APP and collapses consecutive duplicates with an (x14) suffix.

Representative tags include lifecycle, grpc, indexing, http, daemon, security, metrics, resilience, update, vfs, ipc, config, storage, extensions, and air.

Terminal

Trace=lifecycle,grpc ./Air     # only lifecycle + gRPC
Trace=short ./Air              # everything, compressed + deduped

Note

DevLog also exposes EmitOTLPSpan plus the dev_log! and otel_span! macros, which is how tracing output reaches an OpenTelemetry collector.

Generated Protocol Bindings 🧬

Source/Vine/Generated/ is not hand-written. build.rs runs tonic-prost-build over Proto/Air.proto and emits air.rs into this directory, producing both the client and server halves of AirService - the 16 RPCs covering authentication, updates, downloads, indexing, status, resources, and configuration.

build.rs

tonic_prost_build::configure()
    .build_server(true)
    .build_client(true)
    .out_dir("Source/Vine/Generated")

Warning

Edits to Source/Vine/Generated/air.rs are overwritten on the next build - change Proto/Air.proto instead.

Project Structure 🗺️

Element/Air/
├── Cargo.toml                    # Package manifest with feature flags
├── build.rs                      # Build script (tonic/prost codegen)
├── LICENSE                       # CC0-1.0 license
├── Source/
│   ├── Binary.rs                 # Binary entry point
│   ├── Library.rs                # Library root (rlib)
│   ├── DevLog.rs                 # Development logging utilities
│   ├── ApplicationState/
│   │   ├── mod.rs
│   │   ├── ApplicationState.rs   # Central application state
│   │   ├── ConnectionHealthReport.rs
│   │   ├── ConnectionInfo.rs
│   │   ├── ConnectionType.rs
│   │   ├── PerformanceMetrics.rs
│   │   ├── RequestState.rs
│   │   ├── RequestStatus.rs
│   │   ├── ResourceUsage.rs
│   │   └── ServiceStatus.rs
│   ├── Authentication/
│   │   ├── mod.rs
│   │   ├── AuthenticationService.rs
│   │   ├── AuthSession.rs
│   │   ├── CredentialsStore.rs
│   │   └── CryptoKeys.rs
│   ├── Binary/
│   │   ├── mod.rs
│   │   ├── Binary.rs             # Binary initialization
│   │   ├── Monitor/
│   │   │   └── StartMonitoring.rs
│   │   └── Shutdown/
│   │       └── WaitForShutdownSignal.rs
│   ├── CLI/
│   │   ├── mod.rs
│   │   ├── CliHandler.rs
│   │   ├── CliParser.rs
│   │   ├── CommandTypes.rs
│   │   ├── DaemonClient.rs
│   │   ├── OutputFormat.rs
│   │   ├── OutputFormatter.rs
│   │   ├── ResponseTypes.rs
│   │   └── Tests.rs
│   ├── Client/
│   │   ├── mod.rs
│   │   ├── AirClient/            # Typed gRPC client methods
│   │   │   ├── mod.rs
│   │   │   ├── AirMetrics.rs
│   │   │   ├── AirStatus.rs
│   │   │   ├── ApplyUpdate.rs
│   │   │   ├── Authenticate.rs
│   │   │   ├── CheckForUpdates.rs
│   │   │   ├── DownloadFile.rs
│   │   │   ├── DownloadStream.rs
│   │   │   ├── DownloadStreamChunk.rs
│   │   │   ├── DownloadStreamRpc.rs
│   │   │   ├── DownloadUpdate.rs
│   │   │   ├── ExtendedFileInfo.rs
│   │   │   ├── FileInfo.rs
│   │   │   ├── FileResult.rs
│   │   │   ├── GetConfiguration.rs
│   │   │   ├── GetFileInfo.rs
│   │   │   ├── GetMetrics.rs
│   │   │   ├── GetResourceUsage.rs
│   │   │   ├── GetStatus.rs
│   │   │   ├── HealthCheck.rs
│   │   │   ├── IndexFiles.rs
│   │   │   ├── IndexInfo.rs
│   │   │   ├── ResourceUsage.rs
│   │   │   ├── SearchFiles.rs
│   │   │   ├── SetResourceLimits.rs
│   │   │   ├── UpdateConfiguration.rs
│   │   │   └── UpdateInfo.rs
│   │   └── AirServiceProvider/   # Service provider implementations
│   │       ├── mod.rs
│   │       ├── ApplyUpdate.rs
│   │       ├── Authenticate.rs
│   │       ├── CheckForUpdates.rs
│   │       ├── DownloadFile.rs
│   │       ├── DownloadStream.rs
│   │       ├── DownloadUpdate.rs
│   │       ├── GenerateRequestID.rs
│   │       ├── GetConfiguration.rs
│   │       ├── GetFileInfo.rs
│   │       ├── GetMetrics.rs
│   │       ├── GetResourceUsage.rs
│   │       ├── GetStatus.rs
│   │       ├── HealthCheck.rs
│   │       ├── IndexFiles.rs
│   │       ├── SearchFiles.rs
│   │       ├── SetResourceLimits.rs
│   │       └── UpdateConfiguration.rs
│   ├── Configuration/
│   │   ├── mod.rs
│   │   ├── AirConfiguration.rs
│   │   ├── ConfigurationManager.rs
│   │   ├── HotReload.rs
│   │   ├── Schema.rs
│   │   └── Tests.rs
│   ├── Daemon/
│   │   ├── mod.rs
│   │   ├── DaemonManager.rs
│   │   ├── DaemonStatus.rs
│   │   ├── ExitCode.rs
│   │   ├── Platform.rs
│   │   └── PlatformInfo.rs
│   ├── Downloader/
│   │   ├── mod.rs
│   │   ├── DownloadManager.rs
│   │   ├── RateLimit.rs
│   │   └── Types.rs
│   ├── HealthCheck/
│   │   ├── mod.rs
│   │   ├── DegradationLevel.rs
│   │   ├── HealthCheckConfig.rs
│   │   ├── HealthCheckLevel.rs
│   │   ├── HealthCheckManager.rs
│   │   ├── HealthCheckRecord.rs
│   │   ├── HealthCheckResponse.rs
│   │   ├── HealthStatistics.rs
│   │   ├── HealthStatus.rs
│   │   ├── PerformanceIndicators.rs
│   │   ├── RecoveryAction.rs
│   │   ├── RecoveryActionType.rs
│   │   ├── RecoveryTrigger.rs
│   │   ├── ResourceWarning.rs
│   │   ├── ResourceWarningType.rs
│   │   ├── ServiceHealth.rs
│   │   └── WarningSeverity.rs
│   ├── HTTP/
│   │   ├── mod.rs
│   │   └── Client.rs
│   ├── Indexing/
│   │   ├── mod.rs
│   │   ├── FileIndexer.rs
│   │   ├── IndexResult.rs
│   │   ├── Background/
│   │   │   ├── mod.rs
│   │   │   └── StartWatcher.rs
│   │   ├── Language/
│   │   │   ├── mod.rs
│   │   │   ├── ParseRust.rs
│   │   │   └── ParseTypeScript.rs
│   │   ├── Process/
│   │   │   ├── mod.rs
│   │   │   ├── ExtractSymbols.rs
│   │   │   └── ProcessContent.rs
│   │   ├── Scan/
│   │   │   ├── mod.rs
│   │   │   ├── ScanDirectory.rs
│   │   │   └── ScanFile.rs
│   │   ├── State/
│   │   │   ├── mod.rs
│   │   │   ├── CreateState.rs
│   │   │   └── UpdateState.rs
│   │   ├── Store/
│   │   │   ├── mod.rs
│   │   │   ├── QueryIndex.rs
│   │   │   ├── StoreEntry.rs
│   │   │   └── UpdateIndex.rs
│   │   └── Watch/
│   │       ├── mod.rs
│   │       └── WatchFile.rs
│   ├── Initialize/
│   │   ├── mod.rs
│   │   ├── Build/
│   │   │   ├── mod.rs
│   │   │   └── BuildServer.rs
│   │   ├── Command/
│   │   │   ├── mod.rs
│   │   │   ├── Connect/
│   │   │   │   ├── mod.rs
│   │   │   │   └── ConnectDaemon.rs
│   │   │   ├── HandleCommand.rs
│   │   │   ├── ParseArguments.rs
│   │   │   └── ValidateCommand.rs
│   │   ├── Configure/
│   │   │   ├── mod.rs
│   │   │   ├── Log/
│   │   │   │   └── ConfigureLog.rs
│   │   │   └── Port/
│   │   │       └── SelectPort.rs
│   │   └── Service/
│   │       ├── mod.rs
│   │       ├── Auth/
│   │       │   └── StartAuth.rs
│   │       ├── Download/
│   │       │   └── StartDownload.rs
│   │       ├── Echo/
│   │       │   └── StartEcho.rs
│   │       ├── Health/
│   │       │   └── StartHealthCheck.rs
│   │       ├── Index/
│   │       │   └── StartIndex.rs
│   │       ├── State/
│   │       │   └── CreateState.rs
│   │       ├── Update/
│   │       │   └── StartUpdate.rs
│   │       └── Vine/
│   │           └── StartService.rs
│   ├── Logging/
│   │   ├── mod.rs
│   │   ├── ContextLogger.rs
│   │   ├── LogContext.rs
│   │   ├── LogManager.rs
│   │   ├── LogRotationConfig.rs
│   │   ├── SensitiveDataConfig.rs
│   │   ├── SensitiveDataFilter.rs
│   │   └── StructuredLogEntry.rs
│   ├── Metrics/
│   │   ├── mod.rs
│   │   ├── AggregationValidator.rs
│   │   ├── GetMetrics.rs
│   │   ├── MetricGuard.rs
│   │   ├── MetricsCollector.rs
│   │   ├── MetricsData.rs
│   │   └── MinMaxUpdate.rs
│   ├── Mountain/
│   │   ├── mod.rs
│   │   ├── Constants.rs
│   │   ├── MountainClient.rs
│   │   ├── MountainClientConfig.rs
│   │   └── TlsConfig.rs
│   ├── Plugins/
│   │   ├── mod.rs
│   │   ├── ApiVersion.rs
│   │   ├── EventBus.rs
│   │   ├── Plugin.rs
│   │   ├── PluginCapability.rs
│   │   ├── PluginDependency.rs
│   │   ├── PluginDiscoveryResult.rs
│   │   ├── PluginHooks.rs
│   │   ├── PluginInfo.rs
│   │   ├── PluginLoader.rs
│   │   ├── PluginManager.rs
│   │   ├── PluginManifest.rs
│   │   ├── PluginMessage.rs
│   │   ├── PluginMetadata.rs
│   │   ├── PluginPermission.rs
│   │   ├── PluginRegistry.rs
│   │   ├── PluginSandboxConfig.rs
│   │   ├── PluginSandboxManager.rs
│   │   ├── PluginState.rs
│   │   ├── PluginValidationResult.rs
│   │   └── Test.rs
│   ├── Resilience/
│   │   ├── mod.rs
│   │   ├── BulkheadConfig.rs
│   │   ├── BulkheadExecutor.rs
│   │   ├── BulkheadStatistics.rs
│   │   ├── CircuitBreaker.rs
│   │   ├── CircuitBreakerConfig.rs
│   │   ├── CircuitEvent.rs
│   │   ├── CircuitState.rs
│   │   ├── CircuitStatistics.rs
│   │   ├── ResilienceOrchestrator.rs
│   │   ├── ResilienceTests.rs
│   │   ├── Retry.rs
│   │   └── Timeout.rs
│   ├── Security/
│   │   ├── mod.rs
│   │   ├── ChecksumVerifier.rs
│   │   ├── RateLimitConfig.rs
│   │   ├── RateLimiter.rs
│   │   ├── RateLimitStatus.rs
│   │   ├── SecureBytes.rs
│   │   ├── SecureStorage.rs
│   │   ├── SecurityAuditor.rs
│   │   ├── SecurityEvent.rs
│   │   ├── SecurityEventType.rs
│   │   ├── SecuritySeverity.rs
│   │   ├── SecurityTests.rs
│   │   └── TokenBucket.rs
│   ├── Tracing/
│   │   ├── mod.rs
│   │   ├── PropagationContext.rs
│   │   ├── SamplingConfig.rs
│   │   ├── SpanEvent.rs
│   │   ├── SpanStatus.rs
│   │   ├── TraceGenerator.rs
│   │   ├── TraceMetadata.rs
│   │   ├── TraceSpan.rs
│   │   └── TraceStatistics.rs
│   ├── Updates/
│   │   ├── mod.rs
│   │   ├── ChecksumUtil.rs
│   │   ├── DownloadSession.rs
│   │   ├── InstallationStatus.rs
│   │   ├── PackageFormat.rs
│   │   ├── PlatformConfig.rs
│   │   ├── PlatformDetect.rs
│   │   ├── PlatformMetadata.rs
│   │   ├── RollbackHistory.rs
│   │   ├── RollbackState.rs
│   │   ├── Types.rs
│   │   ├── UpdateChannel.rs
│   │   ├── UpdateInfo.rs
│   │   ├── UpdateManager.rs
│   │   ├── UpdateStatus.rs
│   │   ├── UpdateTelemetry.rs
│   │   └── VersionCompare.rs
│   └── Vine/
│       ├── mod.rs
│       ├── Error.rs
│       ├── Generated/
│       │   ├── mod.rs
│       │   └── air.rs
│       └── Server/
│           ├── mod.rs
│           └── AirVinegRPCService.rs
└── Documentation/
    ├── GitHub/
    │   ├── Architecture.md
    │   └── DeepDive.md
    └── Rust/
        └── doc/                  # Cargo doc output

In the Land Project

Air 🪁 is the persistent background daemon for the Land ecosystem. It communicates with Mountain ⛰️ via Vine 🌿 (gRPC) on port [::1]:50053 and uses Mist 🌫️ for DNS isolation on its HTTP client.

Role	Details
Daemon Process	Persistent executable that runs independently of the main window, even after the window closes
Server Host	Hosts a local `gRPC` server on `[::1]:50053` to accept commands from Mountain ⛰️
Update Delegate	Sole authority for modifying installation files of the parent application
Signer	Handles cryptographic signing of artifacts and secure token storage for user login
Traffic Manager	Proxy/downloader that keeps large network operations off the main renderer process
File Indexer	Maintains a persistent file index with symbol extraction and fast search across the workspace
Health Monitor	Periodically checks all service health with automatic recovery and degradation tracking

Port Allocation

Process	Port	Protocol	Purpose
Air 🪁	`50053`	Vine 🌿 / `Proto/Air.proto` (`gRPC`)	Daemon services - updates, downloads, indexing
Cocoon 🦋	`50052`	`Proto/Vine.proto` (`gRPC`)	VS Code extension hosting

Proto/Air.proto is this repository's own contract and generates the daemon's service surface. Proto/Vine.proto is not a file in this repository - it lives in the Vine 🌿 repository and is named here only to identify what occupies the neighbouring port.

Air is part of the networking/IPC connectivity stack alongside Mist 🌫️ (DNS isolation) and Vine 🌿 (gRPC protocol layer).

Elements Air Does Not Talk To

The remaining Elements sit outside the daemon's runtime path. Air neither imports them nor opens a socket to them, and they are listed here so the boundary is explicit rather than merely unmentioned:

Element	Responsibility	Relationship to Air 🪁
Cache 📦	Process-wide caching primitives	Runs inside Mountain ⛰️, not the daemon
Maintain 💪🏻	Build system, dead-code eliminator and development runner	Build-time only - never linked into the daemon binary
Output ⚫	Build output and artifact management	Produces the artifacts Air later downloads and verifies
Rest ⛱️	`JS` bundler configuration	Build-time only - no runtime surface
Sky 🌌	`Astro`-based UI component layer	Renders in the window; reaches Air only via Mountain ⛰️
Wind 🍃	`TypeScript`/`Effect-TS` service layer	Peer service layer on the `TypeScript` side
Worker 🍩	Service worker - asset caching, offline support, dynamic `CSS`	Browser-context worker, unrelated to the native daemon

Note

This table is a boundary statement: everything above is deliberately absent from the daemon's dependency graph in Cargo.toml.

Typical usage flow:

Spawn: Mountain ⛰️ detects if Air 🪁 is running. If not, it spawns the binary.
Connect: Mountain ⛰️ establishes a Vine 🌿 (gRPC) connection to Air 🪁's local port [::1]:50053.
Delegate: When a user requests an update or large download, Mountain ⛰️ sends a command to Air 🪁 and immediately returns control to the user.
Monitor: Air 🪁 emits progress events back to Mountain ⛰️ to update the UI status bars.

Getting Started 🚀

Prerequisites

Rust 1.95.0 or later (edition 2024)
Protocol Buffer compiler (included via tonic-build build dependency)

Build

cd Element/Air
cargo build --release

Run

# Run with default settings
./Target/release/Air

# Or via cargo
cargo run --bin Air

Available Features

Feature	Description
`default`	Enables `full-services` and `mtls`
`full-services`	Enables `authentication`, `updates`, `downloader`, `indexing`
`authentication`	Token management and credential storage
`updates`	Update lifecycle management
`downloader`	Parallel chunked downloads with resume
`indexing`	File indexing with symbol extraction
`mtls`	Mutual `TLS` for `gRPC` connections
`appimage`	`AppImage` package format support
`deb`	`Debian` package format support
`rpm`	`RPM` package format support

Build with Features

# Default features (full-services + `mTLS`)
cargo build --release

# Minimal daemon (no update/auth/indexing)
cargo build --release --no-default-features

# All features
cargo build --release --all-features

Key Dependencies

Crate / Package	Purpose
`tonic` / `prost`	`gRPC` server and Protocol Buffer code generation
Vine 🌿	Local path dependency - generated `Proto/Air.proto` `gRPC` contracts
Common 🧑🏻‍🏭	Local path dependency - shared types and abstractions
Mist 🌫️	Local path dependency - DNS isolation for HTTP client
`reqwest` / `rustls`	`HTTPS` downloads with `TLS` certificate verification
`tokio`	Async runtime for concurrent I/O and task scheduling
`notify` / `ignore`	File system event watching for real-time index updates
`ring` / `zeroize`	Cryptographic signing and secure credential storage
`tracing`	Structured `JSON` logging with span propagation
`config` / `toml`	Configuration file loading with hot-reload support
`sysinfo` / `systemstat`	System resource monitoring and health checks
`walkdir` / `ignore`	Recursive directory traversal for file indexing

Security 🔒

Air enforces security at multiple layers, isolating sensitive operations from the main application process:

Layer	Mechanism
Process Isolation	Separate daemon process - cryptographic and auth logic never runs in the renderer
Network	`mTLS` for `gRPC` connections, `Mist` 🌫️ DNS isolation for outbound HTTP
Credentials	AEAD encryption via `ring`, `zeroize`-protected memory, key rotation
Rate Limiting	Token bucket algorithm per-endpoint rate limiting
Checksum Verification	All downloaded artifacts verified via `SHA-256` / `MD5` before installation
Audit Logging	Security audit subsystem with severity-classified events
Singleton Enforcement	PID locking prevents duplicate daemon instances

Compatibility

Air is designed to be compatible with:

Target	Integration
Mountain ⛰️	Communicates via `gRPC` on port 50053 - delegates updates, downloads, indexing, auth
Vine 🌿	Uses `Proto/Air.proto` `gRPC` contracts for all inter-process communication
Mist 🌫️	Uses DNS isolation for all outbound HTTP requests
Cocoon 🦋	Shares port allocation awareness - Cocoon occupies port 50052, Air occupies 50053
Echo 📣	StartEcho service initializes Echo task scheduling within the daemon process

API Reference

Rust API Documentation 📖
Deep Dive
- Detailed startup sequence, gRPC routing, and data flow

License ⚖️

This project is released into the public domain under the Creative Commons CC0 Universal license. You are free to use, modify, distribute, and build upon this work for any purpose, without any restrictions. For the full legal text, see the LICENSE file.

Changelog 📜

Stay updated with our progress! See CHANGELOG.md for a history of changes.

Funding & Acknowledgements 🙏🏻

Land 🏞️ is proud to be an open-source endeavor. Our journey is significantly supported by the organizations and projects that believe in the future of open-source software.

This project is funded through NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.

Land	PlayForm	NLnet	NGI0 Commons Fund

Project Maintainers: Source Open (Source/Open@editor.land) | GitHub Repository | Report an Issue | Security Policy

Name		Name	Last commit message	Last commit date
.cargo		.cargo
.githooks		.githooks
.github		.github
Documentation		Documentation
Proto		Proto
Source		Source
Target/debug		Target/debug
fix_docs		fix_docs
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
build.rs		build.rs

Navigation Menu

Uh oh!

Uh oh!

Repository files navigation

Air 🪁

Overview

Key Features 🪁

Core Architecture Principles 🏗️

System Architecture

Key Components

Startup Configuration ⚙️

Development Logging 🔍

Generated Protocol Bindings 🧬

Project Structure 🗺️

In the Land Project

Port Allocation

Elements Air Does Not Talk To

Getting Started 🚀

Prerequisites

Build

Run

Available Features

Build with Features

Key Dependencies

Security 🔒

Compatibility

API Reference

Related Documentation

License ⚖️

Changelog 📜

Funding & Acknowledgements 🙏🏻

About

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

Uh oh!

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Air 🪁

Overview

Key Features 🪁

Core Architecture Principles 🏗️

System Architecture

Key Components

Startup Configuration ⚙️

Development Logging 🔍

Generated Protocol Bindings 🧬

Project Structure 🗺️

In the Land Project

Port Allocation

Elements Air Does Not Talk To

Getting Started 🚀

Prerequisites

Build

Run

Available Features

Build with Features

Key Dependencies

Security 🔒

Compatibility

API Reference

Related Documentation

License ⚖️

Changelog 📜

Funding & Acknowledgements 🙏🏻

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages