Installation

Lambo ships as a single lambo binary that carries both runtime surfaces: the MCP server (lambo serve) and the command line verbs. You deploy it in two steps. Install the binary, then write a lambo.toml that says which store and which embedder to use.

That is the whole deployment model. Every released binary carries the full ship adapter set. You move between the in-memory store, SQLite, CockroachDB, and PostgreSQL, or between the fixture, BGE-M3, Gemini, and EmbeddingGemma 2 embedders, by editing config, not by downloading a different build. The one exception is the in-process candle embedder: it ships only in the Metal build for Apple silicon, described below.

Install the binary

Each release carries one lambo binary per platform plus a SHA-256 checksum file. Releases are published for Linux x86_64, Linux arm64 and macOS arm64, with the full ship adapter set compiled in. Apple silicon also gets a Metal build, lambo-<version>-macos-arm64-metal, which adds the in-process candle embedder running on the GPU ([embedder] kind = "candle", device = "metal"). The stock binaries do not carry candle.

1. Run the install script

   curl -fsSL https://github.com/nrynss/lambo/releases/latest/download/install.sh | sh

   The script detects your OS and architecture, downloads the matching binary, verifies its SHA-256 against the published checksum, and installs it to ~/.local/bin.

2. Confirm the install

   lambo --version

To pin a version or choose the install directory, set the variables on sh, the command that reads them. LAMBO_INSTALL_DIR must be writable by the current user.

curl -fsSLo install.sh https://github.com/nrynss/lambo/releases/download/v0.8.0/install.sh
LAMBO_VERSION=0.8.0 LAMBO_INSTALL_DIR="$HOME/bin" sh install.sh

To install the Metal build on Apple silicon, set LAMBO_FLAVOR=metal on sh, the command that reads it. The script verifies its checksum the same way, and refuses metal on any other platform.

curl -fsSL https://github.com/nrynss/lambo/releases/latest/download/install.sh | LAMBO_FLAVOR=metal sh

LAMBO_FLAVOR needs the v0.3.0 install script or later, which the latest URL above serves. To pin the Metal build to a version, download that release’s script and run it pinned:

curl -fsSLo install.sh https://github.com/nrynss/lambo/releases/download/v0.8.0/install.sh
LAMBO_VERSION=0.8.0 LAMBO_FLAVOR=metal sh install.sh

Set LAMBO_DRY_RUN=1 the same way to print the asset and URLs the script would fetch without downloading anything.

There is no Windows binary from v0.3.0: the shared session endpoint does not compile on Windows yet (#39). v0.2.2’s lambo-0.2.2-windows-x86_64.exe is on the releases page.

Write a lambo.toml

The config file picks the store and the embedder at runtime. This one needs no external services at all, because the in-memory store and the fixture embedder are both self-contained.

[store]
kind = "sqlite"
path = "./lambo.db"

[embedder]
kind = "fixture"
dim = 1024

SQLite is a local file, so this still needs no external service, and it survives a restart. Create the schema once with lambo --config lambo.toml provision.

Caution

The in-memory store lives inside one process. It is ideal for a single lambo serve that many agents connect to, because they all share that one process’s graph. It does not survive that process exiting, and a separate command line process cannot read it. Choose sqlite, cockroach, or postgres whenever more than one process is involved.

Every key has an environment variable override. See Configuration for the full set.

Caution

An adapter is compiled into the binary, but its backing service still has to be reachable at runtime. The bge_m3 embedder needs a llama-server, the gemini embedder needs Vertex AI credentials, the cockroach store needs a cluster, and the postgres store needs a server with pgvector.

Run it the first time

Start a server in one terminal and read from it in another.

1. Start a session server

   lambo serve --config lambo.toml --session demo --agent agent-a

2. Write a concept from another terminal

   lambo --config lambo.toml derive --session other --agent agent-b \
     --content "user schema" --kind entity

   Use a second session name, because the server already holds the writer lease on demo.

3. Read it back

   lambo --config lambo.toml recall --session other --query "user schema"

   Recall is a read, so it works whether or not a server holds the session.

Your agent can now connect over MCP. See MCP tools for the tool surface, and End to end for a full walkthrough.

Connect an MCP client

Most MCP clients, such as Claude Code and Cursor, read an mcpServers configuration. Add Lambo as a server and let the client start it over stdio. Point command at your lambo binary and pass the serve arguments.

{
  "mcpServers": {
    "lambo": {
      "command": "/path/to/lambo",
      "args": [
        "--config", "/path/to/lambo.toml",
        "serve",
        "--session", "demo",
        "--agent", "agent-a",
        "--transport", "stdio"
      ]
    }
  }
}

The --config flag comes before serve, because it is a global flag. The serve flags come after. The client launches this process and talks to it over stdio, so you do not start lambo serve yourself when you use a client this way.

Real clients drive this, not only unit tests. Claude Code and the Cursor Agent CLI each complete the handshake and list all seven tools over stdio. OMP, the Oh My Pi harness, is an MCP client out of the box. Two models have driven the tools autonomously: DeepSeek Flash under OMP called derive, recall, and stats against a live CockroachDB session, and Cursor’s model ran derive, record_action, recall, and stats in sequence. Pi needs its MCP adapter installed first, after which it drives all seven tools.

See MCP tools for the per-client breakdown.

To connect over HTTP instead, start the server yourself with --transport http and point your client at http://127.0.0.1:7700.

Caution

The HTTP endpoint is a session writer, so treat it accordingly. On loopback it is unauthenticated by default. Binding anywhere else fails closed and requires a bearer token (--auth-token or LAMBO_AUTH_TOKEN), which every request must then send as Authorization: Bearer <token>. See Configuration.

Set up real embeddings

To use BGE-M3 embeddings, run a local llama-server with an embedding model and point Lambo at it.

llama-server -m path/to/bge-m3.gguf --embedding --port 8080

Then set the embedder in lambo.toml.

[embedder]
kind = "bge_m3"
dim = 1024
url = "http://127.0.0.1:8080"

Caution

Do not switch embedder models in the middle of a session without re-embedding, because vectors from different models are not comparable.

Set up durable storage

For a durable store, apply the schema before you serve. The repository’s scripts/provision.sh does this for CockroachDB. Then select the store in lambo.toml and keep the connection string in the environment, so the secret stays out of the file.

[store]
kind = "cockroach"

export LAMBO_COCKROACH_DSN="postgresql://USER@HOST:26257/lambo?sslmode=verify-full"

For a local file instead, set kind = "sqlite" and path = "./lambo.db". See Configuration for the store keys and the provisioning details.

Build from source

You do not need this to run Lambo. Build from source when you want an unreleased change, a smaller binary, or to work on Lambo itself. You need a stable Rust toolchain from rustup.rs.

git clone https://github.com/nrynss/lambo.git
cd lambo
cargo build --release --features ship
# Apple silicon, with the Metal candle embedder:
cargo build --release --features ship,embed-candle-metal

Cargo writes the binary to target/release/lambo. The stock release binaries are built with --features ship, so the first command matches them. The Metal release asset is built with --features ship,embed-candle-metal, so the second matches that one. You can also install straight from git, which compiles the default branch and may be newer than the latest tag. Without --features, that builds the crate’s default features (the memory store and the fixture and bge_m3 embedders), so add --features ship for the full set:

cargo install --git https://github.com/nrynss/lambo.git --features ship

Cargo features select which adapters are compiled in. List fewer to get a smaller binary.

Feature	What it adds
store-memory	In-memory store. This is the default and needs no external service.
store-sqlite	SQLite store, backed by a local file.
store-cockroach	CockroachDB store, for a hosted cluster.
store-postgres	PostgreSQL store with pgvector (kind = "postgres").
embed-fixture	Deterministic fixture embedder for tests and quick starts.
embed-bge	BGE-M3 embeddings served by llama-server.
embed-gemini	Vertex AI Gemini embeddings (gemini-embedding-001), authenticated with a service account.
embed-eg2	EmbeddingGemma 2 text and image embeddings served by llama-server b11452 or later (kind = "embeddinggemma2"). Builds on embed-bge.
embed-candle	In-process BGE-M3 through candle (kind = "candle"), CPU backend only. Builds anywhere.
embed-candle-metal	embed-candle plus the Metal GPU backend. Apple silicon only. This is what the Metal release asset adds to ship.
embed-candle-accelerate	embed-candle plus Apple’s Accelerate framework for the CPU backend. macOS only.
embed-candle-cuda	embed-candle plus the CUDA GPU backend. Needs a CUDA toolkit at build time and an NVIDIA GPU at runtime. From 0.5.0 it builds against CUDA 13.4 directly (cudarc 0.19.10). 0.4.0’s cudarc knows versions only up to 13.3 (#111), so to build 0.4.0 against CUDA 13.4, set CUDARC_CUDA_VERSION=13030 for the build (a 13.3 build runs on a 13.4 driver).
embed-bedrock	Reserved for Amazon Titan embeddings through Bedrock. Not implemented, so it fails at startup if selected.
recall-elastic	Optional Elasticsearch recall tier, selected by a top-level [recall] section (kind = "elastic"). The index serves recall’s vector leg; the store stays the source of truth. Needs a reachable Elasticsearch cluster at runtime.

The ship feature turns on every store and embedder above except embed-bedrock and the embed-candle family, plus recall-elastic. Choosing features only changes what the binary can do. Which store and embedder it does use is still a lambo.toml decision.