Getting Started
Getting Started
This guide walks you through installing 8Vast, starting the daemon, and running your first search. By the end, you'll have a working setup and understand the basics.
Install
On macOS (Apple Silicon):
brew install 8vast
This installs the 8v command-line tool. cargo install 8vast is coming soon for other platforms.
Start the daemon
8Vast runs as a daemon — a background service that handles everything. The desktop app and the CLI both connect to it. The daemon manages your projects, runs searches, coordinates workflows, and exposes tools to AI assistants.
Start it in the foreground to see what it does:
8v daemon run
You'll see log output as it starts up, discovers projects, and begins listening for connections. Press Ctrl+C to stop it.
For day-to-day use, install it as a system service so it starts on boot:
8v daemon install
8v daemon start
Check that it's running:
8v daemon status
You should see the daemon's version, uptime, and the address it's listening on (default: 127.0.0.1:3001).
Your first project
A project is a directory that 8Vast knows about. When you register a directory as a project, the daemon detects your git repos, identifies the default branch, and derives a project name.
cd /path/to/your/code
8v project init
That's it. The daemon now tracks this directory. You can list your projects:
8v project list
Each project gets its own index, its own work sessions, and its own persistent memory. But you don't need to set any of that up yet — it happens as you use 8Vast.
Search your code
8Vast builds a search index over your code. The index supports two modes: keyword search (BM25, the same algorithm search engines use) and semantic search (embedding-based, which understands meaning). By default, it uses both — hybrid mode.
Build the index:
8v search index .
This scans the current directory, tokenizes files for BM25, and generates semantic embeddings. The first run takes a few seconds depending on the size of your codebase.
Search it:
8v search find "authentication"
This returns files ranked by relevance. BM25 finds exact keyword matches. Semantic search finds files that are about authentication even if they don't use that word.
Try a natural-language query to see semantic search in action:
8v search find "how to handle user login" --mode hybrid
Hybrid mode (the default) combines both ranking signals. You can also use --mode bm25 or --mode semantic to use one or the other.
For more detail on how search works — scoring, indexing strategies, query modes — see the Search documentation.
Connect your AI
8Vast exposes its capabilities through MCP (Model Context Protocol). MCP is a standard that lets AI assistants call tools — search, file operations, git, workflows, and more.
Connect Claude or any MCP-compatible assistant to:
http://127.0.0.1:3001/mcp
Once connected, the AI gains access to everything 8Vast can do. It can search your code, read and write files, run git operations, and follow workflows. The daemon handles authorization and scoping — the AI only sees projects you've registered.
Three layers
You don't need everything at once. 8Vast has three layers of capability, and you can start with just the first:
Layer 1: Directory. Point 8Vast at any directory. You get file operations, git integration, search, and code intelligence. No setup beyond 8v daemon run.
Layer 2: Project. Run 8v project init in a directory. You get indexing, work sessions, persistent memory, and workflow tracking. The daemon remembers this directory and keeps its index up to date.
Layer 3: Organization. Run 8v auth login to connect to an organization. You get problems, features, documents, cross-project sync, and collaboration. This is where 8Vast becomes a shared system for teams.
Start with layer 1. Move to layer 2 when you want search and memory. Move to layer 3 when you need coordination across people and projects.