Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Environment Setup

Audience and Use

This page is for developers and platform teams preparing a reliable local or shared environment for Locus evaluation and integration.

Use it to:

  1. Confirm supported tooling and runtime combinations.
  2. Validate environment readiness before implementation work starts.
  3. Standardize local, CI, and staging setup patterns.

Support Matrix

ComponentSupported BaselineNotes
Rust toolchainStable channelUse a pinned stable toolchain in CI for reproducibility.
CargoBundled with Rust stableRequired for build, test, examples, and docs generation.
OS (development)Linux, macOS, Windows (WSL2 recommended)Linux and macOS are primary paths for host scripting.
Container runtimeDocker Engine or compatible runtimeRequired for image-based MCP and gateway startup paths.
Storage backendIn-memory or SurrealDB v3In-memory for fast local validation; SurrealDB for persistent environments.
Docs toolchainmdbook, mdbook-mermaidRequired for generated technical docs site.

Tooling Prerequisites

Install and verify:

rustc --version
cargo --version
docker --version
mdbook --version
mdbook-mermaid --version

If docs tools are missing:

cargo install mdbook
cargo install mdbook-mermaid

Local Development Profile

Use when iterating on features and integration code.

  1. Storage: in-memory or local SurrealDB.
  2. Host runtime: single process.
  3. Objective: speed and repeatability.

CI Validation Profile

Use for pull requests and release gating.

  1. Storage: deterministic in-memory fixtures.
  2. Host runtime: test-only jobs.
  3. Objective: compatibility and regression detection.

Staging Profile

Use for pre-production verification.

  1. Storage: isolated remote SurrealDB.
  2. Host runtime: gateway and MCP parity checks.
  3. Objective: rollout rehearsal and migration validation.

Baseline Verification

From repository root:

cargo check --workspace --examples
cargo test --workspace
cargo check --examples -p locus-sdk
./docs/build-technical-docs.sh

A setup is considered ready when all commands complete successfully.

Runtime Smoke Start

Image-based MCP:

docker run --rm -i -v "$PWD/locus-data:/data" ghcr.io/entasislabs/locus-mcp:0.1.0

Image-based gateway:

docker run --rm -p 8080:8080 -p 8081:8081 -v "$PWD/locus-data:/data" ghcr.io/entasislabs/locus-gateway:2.0.0

Environment Hygiene Controls

  1. Keep secrets outside repository files.
  2. Keep development and production data paths separate.
  3. Pin model and provider settings in shared environments.
  4. Use explicit tenant and session scope in integration tests.

Exit Criteria

Environment setup is complete when:

  1. Workspace build and tests pass.
  2. At least one host runtime starts successfully.
  3. Technical docs site builds successfully.
  4. Team members can reproduce setup using this page only.