Installing Tribal
Configuring Tribal
This skill walks through the four steps that configure Tribal: install the binary, run
, run
, and wire the MCP config into your harness. An optional fifth step extends the check suite with provider readiness probes before the user's first ingest. Follow the steps in order.
If
should activate after configuration is complete, this skill hands off at the end.
Before you start
IMPORTANT: Load
before doing anything else. It is the ask-first protocol for credential-bearing files. This skill touches several of those during wire-up, and skipping the protocol risks reading or writing user secrets without consent.
Also load
. It carries the detection one-liner (
) and the single source for what varies across macOS Intel, macOS Apple Silicon, and Linux. The steps below assume the active platform is known.
Step 1: Install the binary
Three install paths, below. Which one fits is the user's call, because the consequences land on them: the binary (Homebrew on macOS, the shell installer on Linux) is the lightest to run, upgrade, and remove, but needs a Postgres they supply; Docker Compose bundles its own Postgres but leaves a long-running container, HTTP transport, and secrets in a
to manage. The binary is the simpler default for most, but it is a trade-off to put to the user, not a choice to make for them, so confirm the path before installing.
Homebrew (macOS)
bash
brew install tribal-memory/homebrew-tap/tribal
Installs a
binary on PATH. Homebrew resolves the architecture. The harness can spawn the binary per session, or run it as a long-running server (Step 2).
Shell installer (macOS and Linux)
bash
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/tribal-memory/tribal/releases/latest/download/tribal-installer.sh | sh
Targets macOS and Linux. Same end state as Homebrew: a single binary on PATH.
Docker Compose (containerised)
Runs Tribal as a long-running server in a container, alongside a bundled Postgres. The harness wires to the container over the network. Requires HTTP transport (Step 2 explains why).
The only file the user needs is
; the entrypoint is baked into the published image. The image tag is pinned inside that file, so the compose file and the image must come from the same release.
Take the compose file from the latest release, into a fresh directory.IMPORTANT: reusing an existing local checkout is a trap. A stale checkout pins an old image tag in its compose file, so
silently runs that old version; that is why the steps fetch into a fresh directory. If a checkout is reused, bringing it to the latest release tag first (
, then check out that tag) avoids the stale pin.
One way to fetch the release compose into a clean directory:
bash
tag=$(curl -fsSL https://api.github.com/repos/tribal-memory/tribal/releases/latest | jq -r .tag_name)
mkdir tribal-docker && cd tribal-docker
curl -fsSL "https://raw.githubusercontent.com/tribal-memory/tribal/$tag/docker-compose.yml" -o docker-compose.yml
curl -fsSL "https://raw.githubusercontent.com/tribal-memory/tribal/$tag/.env.example" -o .env.example
# Cloud provider? Create .env from .env.example and set its key first (see below).
docker compose up
reads
, not
, so copy the template to
and edit that one. With no
(or its defaults), the stack runs on a local Ollama.
IMPORTANT: for a cloud provider, set the provider, model, and key in
before that first
. Tribal validates provider config at startup, so a cloud provider without its key fails to boot the container, not just the first ingest.
The example's model values are placeholders, and not every current model works: some are reasoning models Tribal cannot yet drive. Confirm the model against
rather than uncommenting the example blind.
Verify the install
For the direct install paths (Homebrew, shell installer), success is a version string from a fresh shell:
If the command is not found, the installer wrote a PATH update to the shell's rc file that the current session has not re-read. Resolution depends on the active shell; see
.
For the Docker Compose path, success is the
service reporting
:
The binary lives inside the container; the host does not need it on PATH.
If the
service is not
while Postgres reports healthy, a likely cause is
host port 8725 already in use by a previous Tribal stack or another process. Identify what holds it before retrying: a stale Tribal stack can be torn down with the user's agreement; anything else, flag rather than stop. Mapping a free host port is also an option, remembering that the port mapping and
move together.
Step 2: Run
composes setup, project registration, credential persistence, and MCP config emission into one run. Invoke it from inside the git repository the user wants Tribal to know about; bootstrap registers that repository as the project.
The stderr output enumerates the next steps with concrete commands appropriate to the chosen transport, the install state, and whether credentials were written successfully. Treat it as the canonical run-book. The rest of this skill is the meta-frame around that output: what to configure before running bootstrap, what the trade-offs mean, and what to do when the output cannot anticipate the user's environment.
For scripted consumers,
emits the same data as a structured object on stdout (no next-steps prose). The shape is documented in
references/bootstrap-output.md
.
The database URL
Bootstrap needs a Postgres database with the
extension. The connection URL has three resolution channels, in order of precedence: the
flag, the
environment variable, and the
field in the resolved config file.
A local Postgres URL looks like
postgresql://user:pass@localhost:5432/tribal
. The Docker Compose path provides a local Postgres out of the box.
Managed Postgres providers (Neon, Supabase, AWS RDS, and similar) usually require an
parameter and may need provider-specific additions. The Neon shape, for instance, is
postgresql://<user>:<password>@<host>.neon.tech/<database>?sslmode=require
. The provider's dashboard or documentation is the canonical source for the exact URL.
Transport choice
The
flag picks the connection shape between the harness and the Tribal MCP server. Three values:
,
,
. The choice has lifecycle consequences.
- Stdio is the default for direct binary installs. The harness spawns as a subprocess per session and tears it down at session end. No long-lived process to manage.
- HTTP is required for the Docker Compose path (the harness on the host cannot reach into a container's stdio). It is also a valid choice for direct binary installs that want a persistent server reachable from multiple sessions.
- SSE behaves like HTTP for wire-up. Less commonly used.
bash
tribal bootstrap --transport http
HTTP and SSE: the server lifecycle is the user's
For HTTP or SSE transports, the wire-up assumes a
process is running and bound to the registered project ID. Bootstrap's stderr output gives the exact
invocation to run; it does not start the server itself.
How that process runs is for the user to decide. Options include a separate terminal window, a terminal pane (tmux, screen), a backgrounded subprocess, or a service manager (launchd, systemd). The user picks based on their environment.
For the Docker Compose path, the container already runs
as its entrypoint. Nothing additional to manage.
Choosing providers and models
By default Tribal uses a local Ollama. To use a cloud provider, or a non-default local model, set the provider and model for the embedding stage and for each inference stage.
accepts these as flags (
,
, and
--inference-<stage>-provider
/
--inference-<stage>-model
); they can equally be set by environment variable or in the config file. The full set of channels, the per-install-path specifics (the Docker Compose path configures providers through
, not the config file), and current model IDs live in
.
Re-running bootstrap
Re-running
against the same git repository is safe. It reuses the existing project, mints a fresh bearer token, and re-emits the MCP config. Useful when the user wants new credentials, a different transport, or a clean MCP config snippet.
Step 3: Run
Bootstrap's stderr output directs the user to run
. The check command is the canonical diagnostic: it surfaces every configurable failure with a
field that names the next action.
For programmatic consumption, use
. The shape and the walkthrough pattern (act on programmatic remediations, hand off on sensitive ones) live in
references/tribal-check-remediation.md
.
On the Docker Compose path
Run
inside the container, and thread in the project id so the project-resolution check has context:
bash
docker compose exec tribal sh -c 'TRIBAL_PROJECT_ID=$(cat /var/lib/tribal/tribal/project_id) tribal check'
Without the project id, the check reports a
warning even when the install is healthy.
When reports but something is still wrong
covers the configurable surface. Network-level issues (VPN blocking the database path, firewall rules, DNS flakes) can mean Tribal reports healthy while the user cannot do real work.
references/failure-modes.md
covers this disambiguation.
Step 4: Wire Tribal into your harness's MCP config
Bootstrap's stderr output gives the wire-up command directly for Claude Code (
claude mcp add-json tribal "$(tribal mcp-config)"
). For other harnesses, the same canonical
output is the source of truth; the translation to each harness's native shape lives in
.
The command always emits JSON to stdout (no
flag); warnings, if any, go to stderr. The shape (transport discriminator, stdio vs HTTP fields, where the bearer token lives) is documented in
references/bootstrap-output.md
. The agent should run the command and inspect the live output rather than relying on a memorised shape.
On the Docker Compose path, thread the project id in, the same as
; without it,
returns empty:
bash
docker compose exec -T tribal sh -c 'TRIBAL_PROJECT_ID=$(cat /var/lib/tribal/tribal/project_id) tribal mcp-config'
When you only need to confirm the shape rather than wire it, note that the output carries the bearer token in its
header; see
for inspecting it without printing the value to the transcript.
IMPORTANT: the newly-wired server does not appear in the current session until the harness loads it; the Tribal MCP tools will be missing until then. Most harnesses need a session restart; some can reload in-session (Claude Code, via
). The per-harness reference notes which applies; tell the user as part of the handoff.
Per-harness translations
The container around the MCP entry varies per harness: the primary configuration file, its format, the key name, and the wrapper field shape all differ. The translation from Tribal's canonical shape to a given harness's native shape lives in
. Each file there names the harness, its primary config-file path, the field shape it expects, a
snippet that produces that shape from
, and how to verify the harness has loaded the server.
To wire Tribal into a specific harness, read the corresponding file under that directory.
When there is no reference file for the user's harness
The files in
cover the named target harnesses. For any harness without a dedicated file, the canonical
output is still the source of truth. Read the harness's own MCP configuration documentation, identify the field shape it expects, and produce the translation with the user. If the wire-up works and the user is willing to contribute it back, the path is a pull request against
.
Scope: project by default
Most harnesses support per-project and per-user scope for MCP server entries. The recommended default is project scope: a config file at the repository root rather than in the user's home directory. This keeps each repository's Tribal project ID bound to its own MCP entry, so switching repositories switches Tribal projects automatically. User scope is a valid choice when the user wants Tribal available in repositories that have not been bootstrapped, or when they prefer a single global configuration. The per-harness reference files name the scope flags or file paths.
IMPORTANT (HTTP and SSE transports): the MCP entry for HTTP or SSE carries the bearer token in an
header. Wiring that entry at project scope places the token in the harness's project-scoped config file, which is commonly tracked in version control. For HTTP or SSE, prefer a scope the harness keeps out of version control (user scope, or a local uncommitted file). Stdio entries carry no token and are unaffected.
Consent before writing
Wiring up the harness usually means editing the harness's primary configuration file (typically a JSON or TOML at a path under
). Those files are covered by the consent protocol; the agent must ask the user before reading or writing them. See
.
Where the harness exposes a CLI for adding MCP servers (a
style command), prefer it. The CLI is the authorisation surface: it edits the config file as part of the user's authorised invocation, with no separate consent step needed. Direct file edits do require consent.
Step 5: (Optional) Verify provider readiness
extends the diagnostic suite with fatal probes against the embedding and inference providers. Running it is the gate for the user's first real ingest: bootstrap and the standard
complete without touching providers, so a healthy install can still fail to do real work until the providers are configured. An ingest attempted before this probe passes fails on the provider itself, which the standard check never contacted, so the natural order is to clear
before the first ingest.
Bootstrap's stderr output prompts this step as part of the numbered next steps. Run it once the user has configured their provider (a local Ollama with the required models pulled, or API keys for a cloud provider set in the environment).
The remediation pattern is the same as for the core check suite: programmatic remediations the agent performs autonomously, sensitive ones (API keys, environment variables) relayed to the user. See
references/tribal-check-remediation.md
.
Getting API keys to Tribal
If the user has configured a cloud provider, the API key must reach the
process. The channels, and which applies to each install path, are in
: a directly-installed binary reads it from the config file, a stage-specific
, or the standard
/
; the Docker Compose path takes it from
, since the config file inside the container does not drive provider routing. Writing a config or environment file is sensitive; the consent protocol in
applies.
For a one-time check without persistence, prepend the key:
OPENAI_API_KEY=<key> tribal check --providers
.
When the key is supplied through the environment rather than a file Tribal reads on every invocation, the process that consumes it must be (re)started after the value is set: a harness-spawned stdio server needs the harness relaunched; an HTTP server or the Docker stack needs that process restarted. The agent cannot reload another process's environment for itself. The signal that a restart is needed is
failing on a provider auth check, not a direct inspection of the environment.
What can go wrong here
Install-time failures fall into a small set of patterns, almost all of them with structured guidance built into the binary or the reference files:
- Bootstrap itself fails. The standard error names the failure inline. Common cases: database unreachable, git remote undetectable (pass ), credentials write failure (the token is shown inline for manual save).
- returns "command not found" after install. The installer wrote to a PATH the current shell has not re-read. Covered in Step 1's verification subsection.
- fails on first run. Surface the field per the pattern in
references/tribal-check-remediation.md
- Runtime or network-level issues (worker death, transport errors, VPN blocking the database, prompt I/O).
references/failure-modes.md
When in doubt: bootstrap's standard error is the first source of truth;
is the next; the failure-modes reference handles the long tail.
You're done
Configuration is complete. The user's harness now has Tribal wired as an MCP server, and the providers (if configured) are verified.
Remember the reload step from Step 4: the Tribal tools appear only after the harness reloads (or restarts). Make sure the user has done this before relying on Tribal.
For day-to-day use (capturing knowledge, querying it, traversing the graph, diagnosing issues), the
skill takes over. It activates whenever the user signals they want to save an insight, recall prior context, or approach a problem where Tribal might already have relevant knowledge.
References
The skill body is the entry point; the files below carry the depth.
- : read first. The ask-first protocol for credential-bearing files. Applies to every file write this skill might do.
- : read early. Detection one-liner and what varies across macOS Intel, macOS Apple Silicon, and Linux.
references/bootstrap-output.md
- : read when selecting or configuring embedding or inference providers and models, including cloud-provider setup and current model IDs.
references/tribal-check-remediation.md
- : read when wiring Tribal into a specific harness. Each file under the directory covers one harness.
references/failure-modes.md