skybox

Code-repository indexer, graph store, hybrid search, and MCP server. Single static Rust binary, no Node runtime.

Status

Pre-alpha. Phase roadmap tracked in GitHub issues.

What it does

Indexes a codebase into an LBug (KuzuDB-fork) property graph, then exposes it through:

• CLI: skybox index | query | search | status | mcp | serve | wiki | group | gateway | tunnel | ps | snapshot create | generate | export | eval | hooks | watch | doctor | …
• MCP server: stdio + StreamableHTTP, ~50 tools across analysis, indexing, groups, jobs, snapshots, and gateway admin
• HTTP API: REST for web clients, token auth with per-repo ACL

Install

npm install -g @skylence-ai/skybox
skybox login                       # activate this machine (opens the browser)
skybox license accept --yes        # accept the license terms
skybox setup               # instructions snippet + MCP daemon + Claude Code plugin

npm resolves the right platform binary automatically via optional dependencies (see npm/ for the per-platform packages). Supported platforms: macOS (Apple Silicon), Linux (x86-64 / ARM64), Windows (x86-64). See Platform availability below for what's not yet built.

Hand install (no Node, or an unsupported platform)

Prefer npm install -g above for the supported platforms. Otherwise download the matching archive from GitHub Releases and put the binary on your PATH. See Platform availability for the macOS quarantine/codesign remediation a hand-installed binary needs (issue #492).

Architecture

Cargo workspace:

crates/
├── skybox-cli/      # clap-based binary
├── skybox-core/     # ingestion, graph, search, embeddings, groups
├── skybox-mcp/      # MCP server (rmcp)
├── skybox-api/      # axum HTTP API + auth
├── skybox-gateway/  # SQLite-backed auth/ACL gateway for the MCP HTTP server
├── skybox-wiki/     # Markdown wiki + Mermaid diagram generation
└── skybox-eval/     # eval harness (MCP corpus scoring)

Storage per repo: <repo>/.skybox/{lbug.kuzu,meta.json}. Global registry at ~/.skybox/registry.json.

Stack

| Concern | Crate | |---------|-------| | Graph DB | lbug 0.16 (Rust-native KuzuDB fork) | | Parsing | tree-sitter + language grammar crates | | Parallelism | rayon (parse), tokio (I/O + servers) | | Embeddings | fastembed 5 (ort + tokenizers + hf-hub) | | FTS / BM25 | lbug FTS extension | | Vector index | lbug HNSW extension (cosine distance) | | HTTP client | reqwest (sync, rustls) | | MCP | rmcp | | HTTP API | axum, tower, tower-http | | CLI | clap (derive) |

Embedding model: sentence-transformers/all-MiniLM-L6-v2 (384 dims, mean-pooled, L2-normalised). Pulled via fastembed's built-in registry; first skybox index run downloads ~80 MB into the HuggingFace cache (HF_HOME respected).

Optional HTTP embedding backend: set SKYBOX_EMBEDDING_URL + SKYBOX_EMBEDDING_MODEL to point at any OpenAI-compatible /v1/embeddings endpoint and the local model is bypassed.

Supported languages

Accuracy evidence: release/scheduled scorecard runs are generated by cargo run -p skybox-eval --bin scorecard and checked in at crates/skybox-eval/SCORECARD.md. The table below remains the intended capability map; the scorecard is the measured definition/edge coverage snapshot.

| Language | Tier | Edge parity | Framework extractors | |---|---|---|---| | Rust | (none) | Defines · Imports · Calls · HasMethod · Contains | Axum routes, Reqwest HTTP | | PHP | (none) | Defines · Imports · Calls · HasMethod · Contains | Laravel routes, Eloquent, Guzzle, Inertia (PHP side), Blade | | TypeScript | 1a | Defines · Imports · Calls · Inherits · Implements · HasMethod · Contains | Express, NestJS, Hono, Fastify, Remix, SvelteKit, Nuxt, Expo | | JavaScript | 1a | Defines · Imports · Calls · Inherits · HasMethod · Contains | Express, NestJS, Hono, Fastify, Remix, SvelteKit, Nuxt, Expo | | Python | 1b | Defines · Imports · Calls · Inherits · HasMethod · Contains | FastAPI, Flask, Django, SQLAlchemy, Pydantic | | Go | 2a | Defines · Imports · Calls · HasMethod · Contains | net/http, gorilla/mux, chi, gin, echo, fiber, resty | | Vue SFC | 2b | Defines · Imports · HasMethod · Contains | | | Svelte SFC | 2b | Defines · Imports · Calls · HasMethod · Contains | SvelteKit routes | | Astro SFC | 2b | Defines · Imports · Calls · HasMethod · Contains | | | Java | 3 | Defines · Imports · Calls · Inherits · Implements · HasMethod · Contains | | | C# | 3 | Defines · Imports · Calls · Implements · HasMethod · Contains | | | Kotlin | 3 | Defines · Imports · Calls · Inherits · HasMethod · Contains | | | Ruby | 3 | Defines · Imports · Calls · Inherits · HasMethod · Contains | | | Dart | 3 | Defines · Imports · Contains | |

Building

cargo build --release

Requires Rust 1.88+ (edition 2024). ONNX Runtime downloads on first build via the ort crate (CPU-only, rustls TLS). The all-MiniLM-L6-v2 embedding model (~80 MB) downloads on first skybox index run.

Platform availability

Pre-built binaries (both npm and GitHub Releases) cover:

| Platform | Target triple | |---|---| | macOS (Apple Silicon) | aarch64-apple-darwin | | Linux (x86-64) | x86_64-unknown-linux-gnu | | Linux (ARM64) | aarch64-unknown-linux-gnu | | Windows (x86-64) | x86_64-pc-windows-msvc |

Not yet built (build from source via cargo build --release): macOS (Intel), Windows (ARM64).

macOS hand-installed binaries: a binary downloaded via a browser (or extracted from a downloaded tarball) carries the com.apple.quarantine xattr. skybox daemon install mcp strips it and re-signs the binary ad-hoc automatically, but if you install by hand and never run the daemon installer, large-repo indexing can fail with Gatekeeper denials (issue #492). See docs/runbook.md for the manual xattr/codesign remediation and skybox doctor's detection of this state.

Ignoring files

Skybox applies three layers of exclusion during index:

1. Hardcoded lists: binary extensions, build artefacts, lock files, and common dependency directories (see DEFAULT_IGNORE_DIRS in crates/skybox-core/src/pipeline/ignore_filter.rs). Cannot be overridden.
2. .gitignore: standard git ignore rules, respected automatically.
3. .skyboxignore: per-repo custom exclusions in gitignore syntax. Drop this file at the repository root to exclude paths that .gitignore doesn't cover.

# .skyboxignore
vendor/
web/node_modules/
web/dist/

Files matching any of these layers are not indexed and do not appear in search results.

Non-goals

• Web UI: shipped separately in skylence.be.
• Write access via the read-only connection pool: rejected at the query layer.