# Lit — The Agentic-First Distributed Version Control System
**The world's first universal version control system designed for AI agents first and humans second.**
Lit is a complete Git replacement written in Rust — 65+ commands, 30 MCP tools, post-quantum cryptographic security, sandboxed execution, and structured machine-readable output. Every interface is designed for autonomous agent workflows, with human-friendly output available via a single flag.
Unlike Git, Lit is not limited to source code. Its pluggable content type system versions **CAD models, EDA schematics, manuscripts, databases, scientific datasets, media assets, geospatial data**, and any other domain content — with domain-appropriate diff, merge, and storage strategies. Arbitrary agent profiles let CAD designers, EDA engineers, technical writers, DBAs, and data scientists work alongside software agents in a unified versioned workspace. Datacenter deployment features enable cluster sharding, replication, health monitoring, and Prometheus-style metrics for production-scale operation.
## Why Lit?
Git was designed in 2005 for human developers using terminals. Every interface — output formatting, error messages, interactive prompts, conflict markers — assumes a human is reading and responding. AI agents must parse Git's freeform text output with fragile regex, work around interactive prompts, and translate `<<<<<<<` conflict markers into something actionable.
**Lit inverts this.** Every command emits structured JSON by default. Errors include machine-actionable codes and remediation hints. Merge conflicts are structured objects, not text markers. Batch operations accept JSONL on stdin. Nothing ever prompts for input. Humans get the same power through a `--human` flag.
| | Git | Lit |
| ----------------------- | --------------------------- | ---------------------------------------- |
| **Designed for** | Human developers | AI agents (humans supported) |
| **Default output** | Freeform text | Structured JSON |
| **Error handling** | Freeform strings | Typed error codes + remediation |
| **Batch operations** | Shell scripting | Native JSONL batch mode |
| **API access** | Third-party wrappers | Built-in REST + MCP + `lit://` + stdio |
| **Merge conflicts** | `<<<<<<<` markers | Structured conflict objects |
| **Agent metadata** | Commit message conventions | First-class metadata field |
| **Agent coordination** | None | Swarm registration, file leasing |
| **Agent workflow** | Branch → PR → merge | Intent → Commit → Converge |
| **Identity** | None | DID-based identity, UCAN delegation |
| **Trust scoring** | None | Reputation tracking per agent |
| **Issues & PRs** | None built-in | Local-first, stored as git refs |
| **Federation** | Centralized (GitHub/GitLab) | Content-addressed peer-to-peer |
| **Sandboxing** | None | Process isolation with env/fs/net fences |
| **Content types** | Source code only | CAD, EDA, manuscripts, DBs, media, etc. |
| **Agent types** | N/A | SWE, CAD, EDA, writer, DBA, reviewer, CI |
| **Datacenter** | N/A | Sharding, replication, metrics, health |
| **Cryptography** | SHA-1 / SHA-256 | SHA3-512 + BLAKE3 (quantum-resistant) |
| **Signatures** | GPG / SSH | ML-DSA-87 (NIST FIPS 204) |
| **Encryption** | None built-in | AES-256-GCM at rest, TLS 1.3 in transit |
| **Compliance** | None | FIPS 140-3, auto self-test at startup |
| **Interactive prompts** | Frequent | Never (zero-prompt design) |
## Features
- **65+ CLI commands** — full Git-equivalent workflow plus agent-native extensions
- **30 MCP tools** — LLM agents interact via Model Context Protocol tool calls
- **Decentralized identity** -- DID-based identity with Ed25519 and ML-DSA-87 post-quantum keys
- **UCAN capability delegation** -- fine-grained, cryptographically signed permission tokens
- **Agent trust scoring** -- reputation tracking with event-driven trust levels
- **Local-first issues & PRs** -- issue tracker and pull requests stored as git refs
- **Event subscriptions** -- subscribe to repository events (commits, branches, merges)
- **Agent task delegation** -- structured protocol for delegating work between agents
- **Content-addressed federation** -- peer-to-peer repository sync with want-list negotiation
- **4 transport protocols** — HTTPS, SSH, `lit://` (custom TCP), stdio pipe
- **Sandboxed execution** — run untrusted code in isolated environments with filesystem, environment, and network fences
- **Intent → Commit → Converge** — agentic workflow replacing branch/PR with scoped intents, commit attachment, and trust-gated convergence
- **Universal content types** — 30+ built-in types for CAD (STEP, STL, IGES, 3MF), EDA (KiCad, Gerber, SPICE), manuscripts (LaTeX, DOCX, Typst), databases (SQLite, Parquet, CSV), scientific data (HDF5, FITS, Jupyter), media, geospatial, legal, and financial formats — each with domain-appropriate diff, merge, and storage strategies
- **Datacenter deployment** — cluster node management, consistent-hash sharding, configurable replication (sync/async/semi-sync), health monitoring, Prometheus-style metrics, connection pooling, and chunked large-object transfer
- **Generic agent profiles** — 10 built-in profiles (SWE, CAD designer, EDA engineer, writer, DBA, reviewer, CI bot, security auditor, data scientist, orchestrator) with capabilities, trust levels, content type affinity, resource limits, and path-based access control
- **Swarm coordination** — multi-agent registration, file leasing, and conflict-free concurrent access
- **Post-quantum signatures** — ML-DSA-87 (NIST FIPS 204, Security Level 5)
- **FIPS 140-3 compliance** — AES-256-GCM, PBKDF2-HMAC-SHA512, automatic Known Answer Tests at startup
- **Airgap mode** — complete network isolation for classified environments (USB, file shares only)
- **Atomic transactions** — begin/commit/rollback multi-operation sequences
- **Large File Storage** — LFS tracking and migration for binary assets
- **Git interop** — bidirectional import/export with existing Git repositories
- **Command ontology** — machine-readable type graph for agent discovery and SDK generation
- **JSON Schema** — auto-generated draft 2020-12 schemas for all command inputs/outputs
- **Per-IP rate limiting** — sliding window throttle (100 req/60s) on all server endpoints
- **Tamper-evident audit logs** — HMAC-SHA256 signed, append-only operation logs
## Installation
```bash
cargo build --release
cargo install --path .
```
Pre-built binaries for Linux, macOS, and Windows are available on the [Releases](https://github.com/nervosys/Lit/releases) page.
## Quick Start
### For Agents (JSON output — default)
```bash
# Initialize
lit init
# → {"status":"ok","command":"init","path":"/path/to/repo"}
# Stage and commit
lit add src/
lit commit -m "implement feature X"
# → {"status":"ok","command":"commit","hash":"abc123...","tree":"def456..."}
# Check status
lit status
# → {"status":"ok","command":"status","branch":"main","staged":[],"modified":[],"clean":true}
# Batch operations via JSONL stdin
echo '{"op":"add","files":["src/a.rs"]}
{"op":"commit","message":"fix bug"}' | lit batch
```
### For Humans
```bash
# Use --human or -H for familiar output
lit status --human
lit log --human
lit diff --human
# Or set globally
export LIT_OUTPUT=human
```
## Commands (65+)
### Version Control
```bash
lit init [--bare] [path] # Initialize repository
lit add <files...> # Stage files
lit commit -m <message> [--intent <id>] # Record changes (optionally attach to intent)
lit status # Show working tree status
lit log [--count N] # Show commit history
lit diff [--word-diff] [--stat] # Show changes (structured hunks)
lit show <object> # Inspect any object
lit branch [name] [--delete] # Manage branches
lit checkout <target> [-b] # Switch branches
lit merge <branch> # Merge branches (3-way)
lit resolve <file> --strategy=X # Programmatic conflict resolution
lit tag <name> [--sign] # Create tags (with optional PQ signatures)
lit stash [push|pop|apply|list|drop] # Stash work-in-progress
lit reset [--soft|--mixed|--hard] # Move HEAD
lit revert <commit> # Create inverse commit
lit cherry-pick <commit> # Apply specific commits
lit rebase <base> # Replay commits
lit blame <file> # Line-by-line authorship
lit bisect <start|good|bad|reset> # Binary search for bug-introducing commit
lit reflog # Reference update history
```
### Remote Operations
```bash
lit remote add <name> <url> # Add remote
lit push <remote> <branch> # Push to remote (--force available)
lit pull <remote> <branch> # Fetch and merge
lit clone <url> [directory] # Clone repository
lit fetch <remote> [branch] # Download without merging
```
Supported transports: HTTPS, SSH, `lit://` (custom TCP), `file://`, USB/removable media, network shares.
### Agentic Commands
```bash
lit batch # Execute JSONL operations from stdin
lit serve --port 3000 # Launch HTTP REST API server
lit serve --stdio # Launch stdio JSON pipe server
lit serve --daemon # Launch lit:// TCP daemon
lit mcp-serve --stdio # Launch MCP tool server (stdio)
lit mcp-serve --port 8385 # Launch MCP tool server (HTTP)
lit tx <begin|commit|rollback> # Atomic transaction mode
lit snapshot -m <msg> # Add-all + commit in one step
lit search <query> # Full-text search across history
lit watch # Emit filesystem change events as JSON
lit ontology # Output command ontology for agent discovery
lit schema [--command <id>] # JSON Schema (draft 2020-12) from ontology
```
### Swarm Coordination
```bash
lit swarm register <agent-id> # Register an agent in the swarm
lit swarm list # List registered agents
lit swarm lease-acquire --agent <id> --path <file> --duration 300
# Acquire exclusive file lease (seconds)
lit swarm lease-release --agent <id> --path <file>
# Release a file lease
lit swarm lease-list # List all active leases
```
### Sandbox
Run untrusted code in process-isolated environments with filesystem, environment, and network fences:
```bash
lit sandbox init [name] # Create sandbox from working tree
lit sandbox run <name> -- <cmd> # Run command inside sandbox
lit sandbox list # List all sandboxes
lit sandbox destroy <name> # Remove a sandbox
```
Isolation layers:
| Layer | Protection |
| ----------- | -------------------------------------------------------- |
| Filesystem | Working tree copied into `.lit/sandboxes/<name>/` |
| Environment | `env_clear()` — only minimal vars exposed |
| Home / Temp | HOME, USERPROFILE, TEMP, TMP redirected to sandbox dir |
| PATH | Restricted to system directories only |
| Network | `LIT_AIRGAPPED=1` — blocks all network protocols |
| Git config | `GIT_CONFIG_NOSYSTEM=1` — prevents config file leaks |
| Credentials | Cleared — no cloud tokens, SSH keys, or API keys present |
### Identity & Trust
```bash
lit did generate [--method ed25519|ml-dsa-87] # Generate DID identity
lit did show # Show current identity
lit did resolve <did> # Resolve a DID to its document
lit ucan issue <audience> --resource <r> --action <a> # Issue UCAN token
lit ucan list [audience] # List UCAN tokens
lit ucan revoke <cid> # Revoke a UCAN token
lit trust show <did> # Show agent trust score
lit trust list # List all tracked agents
lit trust history <did> # Show trust event history
```
### Issues & Pull Requests
```bash
lit issue create <title> [--body <b>] [--label <l>] # Create issue
lit issue list [--state open|closed|all] # List issues
lit issue show <id> # Show issue
lit issue close <id> # Close issue
lit issue comment <id> <body> # Comment on issue
lit pr create <title> --head <branch> [--base main] # Create PR
lit pr list [--state open|merged|closed|all] # List PRs
lit pr show <id> # Show PR
lit pr merge <id> # Merge PR
lit pr close <id> # Close PR
lit pr comment <id> <body> # Comment on PR
```
### Intent → Commit → Converge
Declare scoped intents, attach commits, and converge work — replacing the branch → PR → merge ceremony:
```bash
lit intent create <title> --agent <id> --scope <paths...> # Declare a scoped unit of work
lit intent list [--status active] [--agent <id>] # List intents
lit intent show <intent-id> # Show intent details
lit intent close <intent-id> # Abandon an intent
lit commit -m <msg> --intent <intent-id> # Attach commit to intent
lit converge <intent-id> [--strategy auto|squash|rebase|accumulate]
# Merge intent into mainline
lit converge <intent-id> --dry-run # Preview convergence
lit converge <intent-id> --verify # Verify commit objects first
```
Intents auto-acquire swarm leases for their scope, detect scope conflicts with other active intents, and support hierarchical decomposition (parent/child intents). The `accumulate` strategy waits for all child intents to converge before merging the parent.
### Content Type Registry
Register, detect, and manage content types for domain-specific versioning. 30+ built-in types cover CAD, EDA, manuscripts, databases, scientific data, media, geospatial, and more — each with appropriate diff, merge, and storage strategies:
```bash
lit content-type list # List all registered content types
lit content-type list --domain cad # Filter by domain
lit content-type show cad/step # Show STEP CAD type details
lit content-type show db/sqlite # Show SQLite database type
lit content-type detect model.step circuit.kicad_pcb # Auto-detect file types
lit content-type register custom/my-format \ # Register custom type
--name "My Format" --domain scientific \
--extensions h5x,hdf --diff-strategy structural \
--merge-strategy schema-aware --storage-tier chunked
```
Built-in domains: **software**, **cad** (STEP, STL, IGES, 3MF), **eda** (KiCad PCB/schematic, Gerber, SPICE), **manuscript** (LaTeX, DOCX, Typst, AsciiDoc), **database** (SQLite, CSV, Parquet, SQL migrations), **scientific** (HDF5, FITS, Jupyter), **media** (image, video, audio), **geospatial** (GeoJSON, Shapefile), **legal** (PDF), **financial** (Excel), **config** (Terraform, Kubernetes).
Each content type specifies:
- **Diff strategy** — text, binary, structural, semantic, or opaque
- **Merge strategy** — 3-way text, manual-resolve, schema-aware, component-level, append-only, or last-writer-wins
- **Storage tier** — standard, LFS, chunked, or external
- **Metadata schema** — JSON Schema fragment for domain-specific fields (triangle count, PCB layers, table schemas, etc.)
### Datacenter Deployment
Cluster management, sharding, replication, health monitoring, and Prometheus-style metrics for production datacenter deployments:
```bash
lit datacenter status # Show cluster overview
lit datacenter register-node node-1 \ # Register a cluster node
--name "us-east-primary" --endpoint 10.0.1.1:9418 \
--region us-east-1 --role primary
lit datacenter configure \ # Configure cluster settings
--replication-factor 3 --shard-strategy consistent-hash \
--replication-mode semi-sync --write-concern 2 \
--metrics-enabled true --metrics-port 9090
lit datacenter health # Run health checks on all nodes
lit datacenter metrics # Collect Prometheus-style metrics
lit datacenter remove-node node-1 # Drain and remove a node
```
**Features:**
- **Consistent-hash sharding** — distribute objects across nodes with virtual shard rings
- **Configurable replication** — synchronous, asynchronous, or semi-sync with tunable write concern
- **Node roles** — primary, replica, relay (edge cache), observer (monitoring only)
- **Health monitoring** — heartbeat-based liveness detection with configurable timeout
- **Prometheus metrics** — `lit_objects_total`, `lit_objects_size_bytes`, `lit_cluster_nodes_healthy`, etc.
- **Connection pooling** — configurable per-node connection pool size
- **Chunked transfer** — large objects split into configurable chunks for inter-node transfer
- **Domain-affinity sharding** — keep a content domain's objects co-located for locality
### Agent Profiles
Domain-specific agent profiles with capabilities, trust levels, content type affinity, and resource limits — enabling arbitrary agents beyond software engineering:
```bash
lit agent-profile list # List all profiles
lit agent-profile list --domain cad # Filter by domain
lit agent-profile show cad-designer # Show CAD designer profile
lit agent-profile capabilities # List all capabilities across domains
lit agent-profile capabilities --domain eda # EDA-specific capabilities
lit agent-profile register my-bot \ # Register custom profile
--name "My Custom Agent" --domain devops \
--capabilities read,write,deploy,test \
--trust-level elevated \
--content-types config/terraform,config/kubernetes \
--allowed-paths 'infra/**,deploy/**'
lit agent-profile remove my-bot # Remove custom profile
```
**Built-in profiles (10):**
| Profile | Domain | Capabilities | Trust | Content Types |
| ------------------ | ----------- | ----------------------------------------------------------- | -------- | ---------------------------- |
| `swe-default` | Software | read, write, branch, merge, test, diff, intent, converge | standard | All source code |
| `cad-designer` | CAD | read, write, branch, lfs, diff, intent, structural-analysis | standard | STEP, STL, IGES, 3MF |
| `eda-engineer` | EDA | read, write, branch, diff, intent, structural-analysis | standard | KiCad, Gerber, SPICE |
| `tech-writer` | Writer | read, write, branch, diff, intent, content-metadata | standard | LaTeX, DOCX, Typst, AsciiDoc |
| `dba` | DBA | read, write, branch, diff, intent, schema-management | elevated | SQLite, CSV, Parquet, SQL |
| `reviewer` | Reviewer | read, review, diff, converge | elevated | All (read-only) |
| `ci-bot` | CI | read, test, deploy, security-scan, diff | elevated | All |
| `security-auditor` | Security | read, review, security-scan, diff | elevated | All (read-only) |
| `data-scientist` | DataScience | read, write, branch, lfs, intent, schema-management | standard | HDF5, Jupyter, Parquet, CSV |
| `orchestrator` | General | read, orchestrate, intent, converge, review | admin | All |
Each profile enforces:
- **Capabilities** — what operations the agent can perform
- **Content type affinity** — which file types the agent is designed for
- **Path-based access control** — allowed/denied glob patterns
- **Resource limits** — max file size, storage quota, files per commit, concurrent leases, rate limits
- **Trust level** — untrusted → limited → standard → elevated → admin
### Events & Delegation
```bash
lit subscribe add <event-types...> [--branch <b>] # Subscribe to events
lit subscribe list # List subscriptions
lit subscribe remove <id> # Remove subscription
lit subscribe events [--event-type <t>] [--limit N] # Read recent events
lit delegate create <to> <title> [--priority high] # Delegate task to agent
lit delegate accept <task-id> # Accept delegated task
lit delegate complete <task-id> <result> # Complete task
lit delegate list [--agent <did>] [--status <s>] # List tasks
lit delegate show <task-id> # Show task details
```
### Federation
```bash
lit peer add <did> --endpoint <url> --public-key <hex> # Add peer
lit peer remove <did> # Remove peer
lit peer list # List all peers
lit peer show <did> # Show peer details
lit peer sync <did> # Sync with peer
```
### Large File Storage
```bash
lit lfs track <patterns...> # Track file patterns (e.g., "*.bin")
lit lfs migrate [--threshold N] # Migrate existing large files to LFS
```
### Maintenance & Migration
```bash
lit verify # Full repository integrity check
lit gc # Garbage collection — pack loose objects
lit import-git <source> # Import from Git repository
lit export-git <destination> # Export to Git format
lit rotate-key # Rotate encryption passphrase
lit config [get|set|show] # Manage configuration settings
```
## Structured Errors
All commands return typed `LitError` values with machine-actionable codes, not freeform strings:
```json
{
"status": "error",
"command": "commit",
"code": "REPO_NOT_FOUND",
"message": "Not a lit repository (or any parent up to /)",
"suggestions": ["Run 'lit init' to create a new repository"]
}
```
Error codes: `ENCRYPTION_ERROR`, `IO_ERROR`, `CONFIG_ERROR`, `NETWORK_ERROR`, `REPO_NOT_FOUND`, `OBJECT_NOT_FOUND`, `INDEX_ERROR`, `MERGE_CONFLICT`, `AUTH_FAILURE`, `INVALID_INPUT`, `PERMISSION_DENIED`, `TIMEOUT`, `PROTOCOL_ERROR`, `INTERNAL_ERROR`, `GENERAL_ERROR`.
## Ontology & JSON Schema
Lit ships a built-in ontology — a typed knowledge graph of every command, type, relationship, and classification in the system. Agents use this for self-discovery, SDK generation, and input validation.
```bash
# Machine-readable ontology (JSON)
lit ontology
# Full JSON Schema (draft 2020-12) — all types and command interfaces
lit schema
# Single command schema
lit schema --command commit
# → {"$schema": "https://json-schema.org/draft/2020-12/schema",
# "input": {"properties": {"message": {"type": "string"}, ...}}}
```
The schema is auto-generated from the ontology — types map to `$defs`, commands map to input/output schemas with metadata (idempotent, safe, side_effects, preconditions). See [ONTOLOGY.md](docs/ONTOLOGY.md) for the complete human-readable reference.
## API Server
Four server modes for different integration patterns:
```bash
# HTTP REST API — for agent swarms and CI/CD
lit serve --port 3000 --token $LIT_TOKEN
# stdio JSON pipe — for direct process integration
lit serve --stdio
# lit:// TCP daemon — for custom protocol clients
lit serve --daemon --port 9418
```
```bash
# Example: agent commits via REST
curl -X POST http://localhost:3000/api/v1/commit \
-H "Authorization: Bearer $LIT_TOKEN" \
-d '{"message":"implement feature X","author":"agent-7","sign":true}'
```
All server endpoints enforce per-IP rate limiting (100 requests per 60-second sliding window). Body size is capped at 1 MB.
## MCP Server
Lit exposes itself as an MCP (Model Context Protocol) tool server, enabling LLM agents to interact with repositories directly through tool calls:
```bash
lit mcp-serve --stdio # For stdio-based MCP clients (VS Code, Claude Desktop)
lit mcp-serve --port 8385 # For HTTP-based MCP clients
```
**Tools (30):** `lit_status`, `lit_diff`, `lit_log`, `lit_show`, `lit_blame`, `lit_reflog`, `lit_add`, `lit_commit`, `lit_snapshot`, `lit_branch`, `lit_checkout`, `lit_merge`, `lit_resolve`, `lit_rebase`, `lit_cherry_pick`, `lit_revert`, `lit_reset`, `lit_stash`, `lit_tag`, `lit_push`, `lit_pull`, `lit_fetch`, `lit_clone`, `lit_search`, `lit_verify`, `lit_gc`, `lit_init`, `lit_config`, `lit_ontology`, `lit_schema`.
**Resources:** `lit://status`, `lit://branches`, `lit://log`, `lit://ontology`, `lit://schema`.
## Configuration
```toml
# .lit/config.toml (repo-local) or ~/.litconfig.toml (global)
[core]
default_branch = "main"
[agent]
default_output = "json" # json | human | msgpack
auto_sign = true # sign all commits with PQ signatures
[merge]
default_strategy = "recursive"
auto_resolve = true
[security]
encryption = "aes-256-gcm"
fips_mode = true
audit_log = true
[airgap]
enabled = false # block all network protocols
strict_mode = false # USB-only (no network shares)
```
Configuration priority: CLI flags > environment variables (`LIT_*`) > repo-local > user global > system > defaults.
## Cryptographic Security
| Layer | Algorithm | Standard |
| -------------- | --------------------------------------------- | --------------- |
| **Hashing** | SHA3-512 + BLAKE3 composite (192 hex chars) | NIST FIPS 202 |
| **Signatures** | ML-DSA-87 (Dilithium5), Security Level 5 | NIST FIPS 204 |
| **Encryption** | AES-256-GCM | NIST FIPS 197 |
| **KDF** | PBKDF2-HMAC-SHA512, 600,000 iterations | NIST SP 800-132 |
| **Audit logs** | HMAC-SHA256, tamper-evident | NIST FIPS 198-1 |
| **Compliance** | FIPS 140-3 Level 1, auto self-test at startup | NIST FIPS 140-3 |
| **PQ safety** | Resistant to Shor's and Grover's algorithms | — |
FIPS Known Answer Tests (SHA-256, SHA-512, SHA3-512, HMAC-SHA-256, RNG health) execute automatically on every startup when `fips_mode = true`.
See [ENCRYPTION.md](docs/ENCRYPTION.md), [FIPS_140-3_COMPLIANCE.md](docs/FIPS_140-3_COMPLIANCE.md), and [CRYPTOGRAPHY.md](docs/CRYPTOGRAPHY.md) for details.
## Transport Protocols
Lit auto-detects the transport from the URL and dispatches to the appropriate backend:
| Protocol | URL Format | Use Case |
| ----------- | ---------------------------------- | ------------------------------------- |
| **HTTPS** | `https://host/repo` | Public and private remotes over TLS |
| **SSH** | `ssh://host/repo` or `host:repo` | Authenticated access over SSH tunnels |
| **lit://** | `lit://host:9418/repo` | Custom binary TCP for LAN deployments |
| **file://** | `file:///path/to/repo` | Local filesystem URL |
| **Local** | `/path/to/repo` or `C:\repos\proj` | Bare path — no protocol prefix needed |
| **UNC** | `\\server\share\repo` | Windows network shares (SMB/CIFS) |
| **USB** | `E:\repos\proj` or `/media/usb/..` | Removable media (auto-detected) |
| **stdio** | `lit serve --stdio` | JSON pipe for direct process control |
## Operating Modes
Lit supports four operating modes that can be combined (e.g., sandbox + airgap):
### Standard Mode
Full distributed VCS with all network and local transports enabled. Push, pull, fetch, and clone work over HTTPS, SSH, `lit://`, and local paths.
```bash
lit clone https://github.com/org/repo # HTTPS
lit clone ssh://server/repo # SSH
lit clone lit://192.168.1.10:9418/repo # Custom TCP
lit clone /opt/repos/project # Local path
```
### Local-Only Mode
Operate without any remote configuration — purely local version control. All commands that don't involve a remote work identically. Useful for solo development, offline work, or repositories that never need to synchronize.
```bash
lit init myproject && cd myproject
lit add . && lit commit -m "initial commit"
lit branch feature && lit checkout feature
lit log --human
```
Local-only repos can add remotes later via `lit remote add` with any supported transport.
### Airgap Mode
Complete network isolation for classified and air-gapped environments. All TCP-based protocols (HTTPS, SSH, `lit://`, FTP) are blocked at the transport layer. Only physical and filesystem transports are allowed:
| Transport | Airgap | Airgap Strict |
| ----------------- | ------- | ------------- |
| Local filesystem | Allowed | Allowed |
| `file://` URL | Allowed | Allowed |
| USB / removable | Allowed | Allowed |
| Network shares | Allowed | **Blocked** |
| HTTPS / SSH / lit | Blocked | Blocked |
```bash
lit --airgapped clone file:///media/usb/repo.lit
lit config set airgap.enabled true
lit config set airgap.strict_mode true # USB-only, no network shares
```
Removable media is auto-detected via `GetDriveTypeW` on Windows and mount-point heuristics (`/media/`, `/mnt/`, `/Volumes/`) on Linux/macOS.
See [AIRGAP.md](docs/AIRGAP.md) for complete documentation.
### Sandbox Mode
Run untrusted code in process-isolated environments with filesystem, environment, and network fences:
```bash
lit sandbox init demo
lit sandbox run demo -- python3 -m pytest tests/
lit sandbox destroy demo
```
Every sandboxed process gets:
- **Cleared environment** — `env_clear()` strips all host variables
- **Redirected HOME/TEMP** — point into the sandbox directory
- **Restricted PATH** — system binaries only, no user-installed tools
- **Forced airgap** — `LIT_AIRGAPPED=1` blocks all network protocols
- **No credentials** — no cloud tokens, SSH keys, or API keys present
- **Symlink protection** — symlinks are skipped during sandbox copy to prevent escape
Sandboxes combine with airgap mode automatically. See [EXAMPLES.md § Sandboxed Execution](docs/EXAMPLES.md) and the cross-platform demo scripts in `examples/`.
## Use Cases
- **AI agent swarms** — multiple agents collaborating via structured API with file leasing
- **Hardware design teams** — CAD and EDA engineers versioning PCB layouts, schematics, and 3D models with structural diff and component-level locking
- **Research & publishing** — scientists and authors versioning LaTeX manuscripts, Jupyter notebooks, HDF5 datasets, and FITS astronomical data
- **Database versioning** — schema-aware diffing and merging of SQLite databases, Parquet files, CSV datasets, and SQL migration scripts
- **Datacenter-scale deployments** — distributed clusters with sharding, replication, health checks, and Prometheus metrics
- **CI/CD pipelines** — machine-readable output eliminates fragile text parsing
- **MCP-enabled IDEs** — LLM agents operate on repos through tool calls (VS Code, Claude Desktop)
- **Sandboxed builds** — run untrusted code in isolated process environments
- **Air-gapped environments** — government, defense, critical infrastructure
- **Post-quantum security** — organizations preparing for quantum computing threats
- **Git migration** — import existing Git repos, export back when needed
## Testing
382 tests across unit, integration, and performance suites:
```shell
cargo test --lib -- --test-threads=1 # 68 unit tests
cargo test --test command_tests -- --test-threads=1 # 239 command tests
cargo test --test feature_integration_test # 38 integration tests
cargo test --test performance_benchmarks --release # 9 benchmarks
cargo test --test adversarial_test -- --test-threads=1 # 5 security tests
cargo test --test concurrency_test -- --test-threads=1 # 9 concurrency tests
cargo test --test network_integration_test -- --test-threads=1 # 14 network tests
```
## Documentation
- [QUICKSTART.md](docs/QUICKSTART.md) — Getting started guide
- [EXAMPLES.md](docs/EXAMPLES.md) — Usage examples (19 scenarios including sandbox demos)
- [DESIGN.md](docs/DESIGN.md) — Agentic-first architecture and design rationale
- [ARCHITECTURE.md](docs/ARCHITECTURE.md) — System architecture deep-dive
- [ONTOLOGY.md](docs/ONTOLOGY.md) — Complete conceptual reference and type graph
- [ROADMAP.md](docs/ROADMAP.md) — Implementation roadmap and milestones
- [TESTING.md](docs/TESTING.md) — Testing guide
- [ENCRYPTION.md](docs/ENCRYPTION.md) — Encryption system documentation
- [ENCRYPTION_ENHANCEMENTS.md](docs/ENCRYPTION_ENHANCEMENTS.md) — Encryption hardening details
- [CRYPTOGRAPHY.md](docs/CRYPTOGRAPHY.md) — Cryptographic design documentation
- [KEY_DISTRIBUTION.md](docs/KEY_DISTRIBUTION.md) — Key distribution and management
- [FIPS_140-3_COMPLIANCE.md](docs/FIPS_140-3_COMPLIANCE.md) — FIPS 140-3 compliance documentation
- [SECURITY.md](docs/SECURITY.md) — Security model and threat mitigation
- [SECURITY_AUDIT.md](docs/SECURITY_AUDIT.md) — DoD-standard security audit (14 findings, all remediated)
- [AIRGAP.md](docs/AIRGAP.md) — Airgap mode documentation
- [DEPLOYMENT.md](docs/DEPLOYMENT.md) — Deployment and operations guide
- [PROJECT_SUMMARY.md](docs/PROJECT_SUMMARY.md) — High-level project overview
- [CHANGELOG.md](CHANGELOG.md) — Release history
- [CONTRIBUTING.md](CONTRIBUTING.md) — Contribution guidelines
## License
This software is dual-licensed:
- **AGPL-3.0**: Free for open source use under the [GNU Affero General Public License v3.0](LICENSE)
- **Commercial**: Proprietary license available for organizations that cannot comply with AGPL requirements
For commercial licensing inquiries, contact: <licensing@nervosys.ai>
## Security
If you discover a security vulnerability, **do not** open a public issue. See [SECURITY.md](SECURITY.md) for responsible disclosure instructions.
For detailed security architecture: [docs/SECURITY.md](docs/SECURITY.md) | [docs/SECURITY_AUDIT.md](docs/SECURITY_AUDIT.md)
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and submission guidelines.
This is a security-focused tool — all contributions must pass CI, include tests, and preserve structured output.