Skip to content
Nimbus

Run from source

This page is for contributors and integrators who want to run Nimbus directly from the source tree — for example, to test a local change to a connector or to debug Gateway behaviour. End users should follow Install instead.

Prerequisites

Section titled “Prerequisites”
Dependency Version Notes
Bun v1.2 or newer Verify with bun --version.
Git any recent The build embeds the short SHA and dirty flag.
Linux only: libsecret-1-dev system package Required by the Vault. sudo apt install libsecret-1-dev on Debian / Ubuntu.
Optional: Rust toolchain stable Only needed if building the Tauri desktop UI under packages/ui.

bun run dev-doctor from the repo root checks every requirement above and prints actionable remediation for anything missing.

Clone and install

Section titled “Clone and install”
Terminal window
git clone https://github.com/nimbus-agent/Nimbus.git
cd Nimbus
bun install

The first bun install resolves the workspace and downloads sharp and @xenova/transformers for the local embedding pipeline. This can take a minute on a first-time install and is cached for subsequent runs.

Run the Gateway and CLI

Section titled “Run the Gateway and CLI”

In one terminal, start the Gateway in the foreground (logs stream to stdout):

Terminal window
bun run --filter @nimbus/gateway dev

In a second terminal, run the CLI against the running Gateway:

Terminal window
bun run --filter @nimbus/cli dev -- ask "what is in my Drive?"

Or use the built binary if you have added packages/cli/dist to your PATH:

Terminal window
nimbus ask "what is in my Drive?"

Workspace layout

Section titled “Workspace layout”
Package Role
packages/gateway The Gateway — JSON-RPC IPC, agent runtime, MCP mesh, Vault, local SQLite index.
packages/cli The nimbus command — thin client, talks to the Gateway over the local socket.
packages/ui The Tauri 2.0 desktop app (Rust shell + React renderer).
packages/mcp-connectors/* First-party MCP servers (Google Drive, Gmail, GitHub, Slack, Linear, etc.).

The Gateway never imports from the CLI or UI; clients communicate with the Gateway exclusively over JSON-RPC. See the Architecture overview for the full subsystem map.

Useful scripts

Section titled “Useful scripts”
Terminal window
bun run typecheck            # Strict TypeScript check across the workspace
bun run lint                 # Biome (format + lint)
bun test                     # Unit + integration tests
bun run test:integration     # Integration tests against real SQLite
bun run docs:build           # Build this documentation site
bun run dev-doctor           # Contributor environment health check

The full command catalogue lives in the repository’s CLAUDE.md and the per-package package.json files.

Next steps

Section titled “Next steps”
  • Read the Architecture overview before touching the Engine, Vault, or HITL executor.
  • For connector authoring, see the contributor walkthrough at docs/contributors/extension-author-walkthrough.md in the repository.
  • Review the contributor checklist at docs/CONTRIBUTING.md before opening a pull request.