Quickstart - Orinadus

1. Build

git clone https://github.com/orinadus-systems/urchin
cd urchin
cargo build

The binary lands at target/debug/urchin. For a release build:

cargo build --release
# → target/release/urchin

To install to ~/.cargo/bin (puts urchin on PATH):

cargo install --path crates/urchin-cli

2. Verify

urchin doctor

Output shows identity (account + device), config source, vault path, journal path, intake port, and current journal stats. If the journal does not exist yet, event count will be 0 — that is normal.

3. Start the daemon

urchin serve

This starts:

The HTTP intake server on 127.0.0.1:18799
A background collector tick loop that runs every configured collector

The daemon runs in the foreground. Use a process supervisor or your shell’s backgrounding to keep it running across sessions. Verify it is up:

curl http://127.0.0.1:18799/health

{"status":"ok","events":0,"ephemeral":false}

4. Ingest your first event

urchin ingest --content "First event" --source cli

Or via HTTP:

curl -s -X POST http://127.0.0.1:18799/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "id": "00000000-0000-0000-0000-000000000001",
    "timestamp": "2026-01-01T00:00:00Z",
    "source": "cli",
    "kind": "conversation",
    "content": "First event"
  }'

{"id":"00000000-0000-0000-0000-000000000001","status":"ok"}

5. Connect an IDE

VS Code / Copilot
Cursor
Zed

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "urchin": {
      "type": "stdio",
      "command": "urchin",
      "args": ["mcp"]
    }
  }
}

Restart VS Code. The Copilot Chat agent now has access to all 10 Urchin MCP tools.

The repo ships .cursor/mcp.json. Open the repo in Cursor and it picks up automatically.

{
  "mcpServers": {
    "urchin": {
      "command": "urchin",
      "args": ["mcp"]
    }
  }
}

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "urchin": {
      "command": {
        "path": "urchin",
        "args": ["mcp"]
      }
    }
  }
}

After connecting, run urchin_status in the assistant to confirm the substrate is reachable.

6. Run a collector

# Shell history
urchin collect shell

# Git commits in a repo
urchin collect git --repo /path/to/your/repo

# All collectors at once
urchin collect all

Next steps

How it works — journal internals, write safety, ephemeral mode
Configuration — set vault path, journal path, tokens
CLI reference — all subcommands and flags

​1. Build

​2. Verify

​3. Start the daemon

​4. Ingest your first event

​5. Connect an IDE

​6. Run a collector

​Next steps