Local Server
Start, stop, inspect, or run the Zvec-Grep local service from the CLI.
Most users do not need to manage the Server. The CLI defaults to auto: it uses a ready local service when available and otherwise runs directly. A running service with an incompatible protocol is reported as an error. The default stdio Agent integration starts and reconnects the service automatically.
Manage it explicitly only for repeated CLI queries, HTTP MCP connections, or troubleshooting. A resident process can:
- share one loaded Embedding model and its runtime resources;
- avoid reinitializing search resources for every command;
- reduce model cold starts across terminals and scripts.
Manage the Service
| Command | Purpose |
|---|---|
zg --server on | Start the service in the background |
zg --server status | Show its current state |
zg --server status --check-ready | Exit non-zero unless it is ready |
zg --server run | Run it in the foreground |
zg --server off | Stop the background service |
zg --server on
zg --server status --check-ready
zg --server offUse foreground mode when you want the process and logs in the current terminal:
zg --server runClient Mode
The CLI supports direct, server, and auto modes. Override the default auto mode with ZVEC_GREP_MODE or --mode:
ZVEC_GREP_MODE=server zg "release checklist"
zg --mode server "release checklist"ZVEC_GREP_SERVER_URL selects the service URL used by CLI clients.
MCP Toolsets
zg --server --stdio starts or reuses the daemon and proxies MCP over stdin/stdout. The default agent toolset exposes only zvec_grep_search. Use --mcp-toolset full on zg --install or zg --server to also expose zvec_grep_rg, zvec_grep_index, zvec_grep_index_drop, zvec_grep_index_status, and zvec_grep_server_status.
Listen Address and Authentication
The service listens on loopback and defaults to 127.0.0.1:7999. Override the address when starting it explicitly:
zg --server on --listen 127.0.0.1:7999
zg --server run --listen 127.0.0.1:7999Authentication is disabled by default on loopback. Use a token file or environment variable to require Bearer authentication:
zg --server on --token-file /path/to/token
ZVEC_GREP_SERVER_TOKEN="your-token" zg --server runRelated settings are ZVEC_GREP_SERVER_TOKEN, ZVEC_GREP_SERVER_TOKEN_FILE, and ZVEC_GREP_HOME. Workspace indexes remain under <root>/.zvec-grep/.
Server logs are stored in <home>/daemon/logs/server.log; startup failures are recorded in <home>/daemon/bootstrap.log. The default home is ~/.zvec-grep.
Restart the service after changing environment settings that affect its Embedding runtime.
For current options, run zg --help server and zg --help environment. If the service does not become ready, see Troubleshooting.