Skip to the content.

Running fleetlens for a team

There are two ways to run the server, and the difference is not scale but who owns the process.

  transport who starts it auth
One engineer, one laptop stdio the MCP client the operating system
A team, one shared index HTTP you a shared bearer token

Start with stdio. Move to HTTP when you want one index built once rather than every engineer indexing the same repositories on their own machine.

Try it locally first

No deployment, no token, no container.

fl index-all /path/to/your/repos --db "$PWD/fleetlens.db"

Absolute paths in the client config, for both the executable and the index. The client starts fl in a working directory of its own and without your shell’s PATH, so a relative --db points somewhere else and a bare fl may not be found at all.

{
  "mcpServers": {
    "fleetlens": {
      "command": "/absolute/path/to/fl",
      "args": ["serve", "--db", "/absolute/path/to/fleetlens.db"]
    }
  }
}

If that answers useful questions about your fleet, the rest of this page is worth doing. If it does not, no amount of deployment will fix that.

Serve a team with Docker

This is the shortest path and it does not care what the host runs.

export FLEETLENS_TOKEN=$(openssl rand -hex 32)

Point FLEETLENS_REPOS at your checkouts, build the index, then serve it:

FLEETLENS_REPOS=/path/to/your/repos docker compose run --rm index
docker compose up -d serve
curl -s localhost:8081/healthz

That is the whole deployment. docker-compose.yml is in the repository root and is about fifty lines; read it rather than treating it as magic.

Serve a team without Docker

Same thing, managed by systemd. Set these three once, in the shell you run the rest of this section in. Every command below, the unit files included, is written in terms of them, so changing a path here is the only edit you have to make:

FLEETLENS_HOME=/opt/fleetlens          # the directory fleetlens owns; the index lives here
FLEETLENS_REPOS=/srv/repos             # your checkouts; can be anywhere
FLEETLENS_USER=fleetlens               # the account that runs it

$FLEETLENS_HOME is fleetlens’s own directory. The index lives there, and so do pin snapshots, so it has to be writable by the account that serves. The repositories are separate and must also be writable by $FLEETLENS_USER, because indexing writes a .context/ directory into each one. Those two are the only non-obvious permissions here.

Create the account and the directories first. The unit below runs as $FLEETLENS_USER, so anything it writes has to belong to that account:

sudo useradd --system --home-dir "$FLEETLENS_HOME" --shell /usr/sbin/nologin "$FLEETLENS_USER" || true
sudo mkdir -p "$FLEETLENS_HOME"
sudo chown -R "$FLEETLENS_USER:$FLEETLENS_USER" "$FLEETLENS_HOME" "$FLEETLENS_REPOS"

Install as that account. The directory belongs to it now, so building the virtualenv as yourself fails on a fresh machine, and where it does succeed it leaves a tree the service cannot update:

sudo -u "$FLEETLENS_USER" python3 -m venv "$FLEETLENS_HOME/venv"
sudo -u "$FLEETLENS_USER" "$FLEETLENS_HOME/venv/bin/pip" install \
  "fleetlens[all] @ git+https://github.com/tata1mg/fleetlens.git@v0.3.1#subdirectory=packages/fleetlens"

fleetlens is not on PyPI, so the install is from git. Pin the tag rather than tracking main: an index built by one version is not guaranteed to be readable by another.

sudo npm install -g @sourcegraph/scip-python @sourcegraph/scip-typescript
sudo -u "$FLEETLENS_USER" "$FLEETLENS_HOME/venv/bin/fl" doctor

Put the token and the paths in one env file next to the index, so the server and the refresh timer read the same source. FLEETLENS_REPOS goes in because nothing else tells the timer where the checkouts are. systemd reads this file as root before dropping privileges, so it never has to be readable by you:

printf 'FLEETLENS_HOME=%s\nFLEETLENS_REPOS=%s\nFLEETLENS_TOKEN=%s\n' \
  "$FLEETLENS_HOME" "$FLEETLENS_REPOS" "$(openssl rand -hex 32)" \
  | sudo -u "$FLEETLENS_USER" tee "$FLEETLENS_HOME/.env" > /dev/null
sudo chmod 600 "$FLEETLENS_HOME/.env"

Build the first index, as the same account. Indexing needs FLEETLENS_HOME and nothing else, so there is no env file to source here and the token stays where it is:

sudo -u "$FLEETLENS_USER" env FLEETLENS_HOME="$FLEETLENS_HOME" \
  "$FLEETLENS_HOME/venv/bin/fl" index-all "$FLEETLENS_REPOS"

With FLEETLENS_HOME set there is no --db to pass: the index lands at $FLEETLENS_HOME/data/fleetlens.db, which is where the units below look for it.

Now the unit. A systemd unit is not a shell script: the executable in ExecStart= has to be a literal absolute path, and EnvironmentFile= and ReadWritePaths= are read before the env file they point at, so none of them can say $FLEETLENS_HOME. Rather than hand-substitute the same path in four places, write the file with the shell and let it fill them in:

sudo tee /etc/systemd/system/fleetlens.service > /dev/null <<EOF
[Unit]
Description=fleetlens MCP server
After=network.target

[Service]
User=$FLEETLENS_USER
EnvironmentFile=$FLEETLENS_HOME/.env
ExecStart=$FLEETLENS_HOME/venv/bin/fl serve --http --host 0.0.0.0 --port 8081
Restart=always

# The server never touches the repositories. It reads the index and, when someone pins a
# build, writes a snapshot of it next to the index, so its own directory must stay writable.
ProtectSystem=strict
ReadWritePaths=$FLEETLENS_HOME
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload && sudo systemctl enable --now fleetlens && curl -s localhost:8081/healthz

Keeping the index fresh

The index is a snapshot. Anything merged after it was built is invisible to every tool on the server, which is why get_index_info exists and why the refresh belongs in a timer rather than in someone’s memory.

Build into a new file and rename it into place. The rename is atomic within a filesystem, so no client ever reads a half-written index, and the running server notices the new file and reopens it on the next request. There is no restart and no downtime.

fl index-all "$FLEETLENS_REPOS" --db "$FLEETLENS_HOME/data/fleetlens.db.new" && mv "$FLEETLENS_HOME/data/fleetlens.db.new" "$FLEETLENS_HOME/data/fleetlens.db"

Under Docker the same thing is docker compose run --rm index, which already does the build-and-rename.

On systemd, put it in a timer rather than in someone’s memory. Two units, both reading the same env file as the server:

The escaped \$ below are deliberate: those stay in the file so the shell expands them from the env file at run time, while $FLEETLENS_HOME and $FLEETLENS_USER are filled in now.

sudo tee /etc/systemd/system/fleetlens-reindex.service > /dev/null <<EOF
[Unit]
Description=Rebuild the fleetlens index
After=network.target

[Service]
Type=oneshot
User=$FLEETLENS_USER
EnvironmentFile=$FLEETLENS_HOME/.env
ExecStart=/bin/sh -c '$FLEETLENS_HOME/venv/bin/fl index-all "\$FLEETLENS_REPOS" --db "\$FLEETLENS_HOME/data/fleetlens.db.new" && mv "\$FLEETLENS_HOME/data/fleetlens.db.new" "\$FLEETLENS_HOME/data/fleetlens.db"'
EOF
sudo tee /etc/systemd/system/fleetlens-reindex.timer > /dev/null <<'EOF'
[Unit]
Description=Rebuild the fleetlens index nightly

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload && sudo systemctl enable --now fleetlens-reindex.timer

Pull the checkouts before it runs, from the same timer or whatever already updates them. The index is only as current as the working copies it read.

Pinning an index

fl pin freezes the served index as a named snapshot for a repeatable evaluation. The commands and the full guide are in pinning.md.

The server needs a writable directory for the snapshots: pins/ next to the index by default, or wherever --pins-dir says. Under Compose this is already set up, with the index volume still read-only and a separate fleetlens-pins volume mounted at /pins, so pinning works out of the box and the server still cannot write the index. Change it only if you want the snapshots somewhere specific, by repointing that volume.

On the systemd deployment the snapshots land under $FLEETLENS_HOME, which is why the unit above sets ReadWritePaths rather than ReadOnlyPaths.

Two environment variables set retention: FLEETLENS_RETAIN_PINNED_DAYS (default 30) and FLEETLENS_PIN_EXTEND_MAX_DAYS (default 10, the most one extension may add). The pin routes use the same token as /mcp.

Connecting clients

Engineers need the URL and the token. For Claude Code:

claude mcp add --transport http fleetlens http://<host>:8081/mcp --header "Authorization: Bearer <token>"

For clients configured by file:

{
  "mcpServers": {
    "fleetlens": {
      "type": "http",
      "url": "http://<host>:8081/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Tell them to call get_index_info when an answer looks wrong. Most surprises on a shared server are staleness, not error.

What this does not do

Worth reading before you put it somewhere it does not belong.

If you need per-user identity, replace BearerAuth in fleetlens/server/http.py with your identity provider’s middleware. Nothing else in the server knows how the caller was authenticated.