# Sourcebot: self-hosted code search and code answers across every repository you own

> Sourcebot indexes repositories from multiple code hosts into one searchable, navigable corpus and lets a reasoning model answer questions against it. The Docker Compose path is short; the operational surface behind it is not.

**sourcebot-dev/sourcebot** — Sourcebot is a self-hosted tool that helps humans and agents understand your codebase.

- Repository: https://github.com/sourcebot-dev/sourcebot
- Website: https://sourcebot.dev
- Stars: 3,955 · Forks: 377
- Language: TypeScript
- License: NOASSERTION
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/sourcebot-dev-sourcebot

## The problem Sourcebot solves is repository sprawl, not search speed

Most teams do not have one code host. They have a GitHub organisation, a GitLab group inherited from an acquisition, a self-hosted Gitea instance someone stood up for internal tooling, and a pile of branches nobody pruned. Each host has its own search, and none of them can answer a question that crosses host boundaries, such as where a particular function is defined when the caller lives in one repository and the definition in another.

Sourcebot's stated purpose is to search and navigate across all your repos and branches "no matter where they're hosted". The README lists four capabilities: Ask Sourcebot, code search, code navigation (goto definition and find references), and a built-in file explorer. The audience is therefore teams large enough to have accumulated multiple code hosts and small enough that nobody has built an internal search platform. The second capability is the one that distinguishes it from a plain grep service: goto definition and find references require symbol-level indexing, not just text matching.

## How the pieces fit: Zoekt for the index, Postgres for state, Redis for the queue

The repository layout makes the architecture legible. There is a vendor/zoekt directory, and the Makefile builds it with go build -C vendor/zoekt -o $(CURDIR)/bin ./cmd/..., which produces the zoekt-webserver binary. The root package.json runs that server in development as zoekt-webserver -index .sourcebot/index -rpc. So the actual code search engine is Zoekt, a Go project vendored into this repository rather than pulled as a dependency.

Around Zoekt sits a TypeScript application split into Yarn workspaces: @sourcebot/web for the Next.js interface, @sourcebot/backend for the worker, @sourcebot/db for Prisma and the database layer, @sourcebot/schemas for the config schema, and @sourcebot/query-language for the search syntax. The development script starts four processes at once: zoekt, worker, web, and schemas.

The data flow implied by this layout is: a connection defined in config.json causes the backend worker to clone or fetch repositories, feed them to the indexer, and write index files under .sourcebot/index. Postgres holds application state, and Redis acts as the queue between the web tier and the worker. Ask Sourcebot then sits on top, using the search and navigation tools as function calls for a reasoning model, which is why the README describes answers as "grounded with inline citations" rather than generated from memory alone.

## Installing Sourcebot with Docker Compose and a config.json

The README gives a four-step deployment. First, download the compose file:

```bash
curl -o docker-compose.yml https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/docker-compose.yml
```

Second, create config.json in the same directory. The README's example creates a single GitHub connection that indexes the Sourcebot repository itself, and notes that comments are supported in the file:

```bash
echo '{
    "$schema": "https://raw.githubusercontent.com/sourcebot-dev/sourcebot/main/schemas/v3/index.json",
    "connections": {
        "starter-connection": {
            "type": "github",
            "repos": [
                "sourcebot-dev/sourcebot"
            ]
        }
    }
}' > config.json
```

Third, update the secrets in docker-compose.yml and start the stack. The compose file ships placeholder values and marks them CHANGEME, with generation commands in comments: openssl rand -base64 33 for AUTH_SECRET and openssl rand -base64 24 for SOURCEBOT_ENCRYPTION_KEY. DATABASE_URL and REDIS_URL also carry CHANGEME comments. Then:

```bash
docker compose up
```

Fourth, visit http://localhost:3000. The compose file publishes port 3000 for the application, binds Postgres to 127.0.0.1:5432 and Redis to 127.0.0.1:6379, and mounts ./config.json into the container at /data/config.json with CONFIG_PATH pointing there. A named volume sourcebot_data holds the index, and sourcebot_postgres_data holds the database.

One thing the README does not spell out: the compose file also mounts an optional .env file, and the environment block references AUTH_URL, which defaults to http://localhost:3000. If you deploy behind a reverse proxy on another hostname, that default is wrong and the README's four steps do not mention it.

## Telemetry is on by default and turns off with one variable

The README carries a note that Sourcebot collects anonymous usage data by default, linking to a search query on the public demo that shows a captureEvent call in the repository. The stated rationale is product improvement, and the README says no sensitive data is collected. To disable it, set the SOURCEBOT_TELEMETRY_DISABLED environment variable to true.

For a self-hosted tool that indexes proprietary source code, default-on telemetry is a decision worth noticing rather than a scandal. The variable exists, it is documented, and the call site is discoverable in the repository. But the default means an air-gapped or regulated deployment has to make an explicit change before the first start, and the compose file's environment block does not list SOURCEBOT_TELEMETRY_DISABLED, so it has to be added by hand or supplied through the optional .env file.

## What the deployment documentation leaves unresolved

The README stops at a working local instance. It does not document rollback, index rebuild procedures, or what happens to the index when a connection is removed from config.json. The Makefile offers two destructive helpers, clean and soft-reset, and both flush Redis and run yarn dev:prisma:migrate:reset, but those are development targets, not production runbooks.

The licence is the second unresolved item. The repository metadata reports NOASSERTION, and the topics list includes fair-source. There is a LICENSE.md at the top level, but its terms are not stated in the README. Anyone planning to embed Sourcebot in a commercial product, or to fork it, needs to read LICENSE.md directly rather than assume it matches a familiar open source licence. The gap between a fair-source label and an OSI-approved licence is not cosmetic.

A third gap: the config file reference is linked, not reproduced. The README points to docs.sourcebot.dev for the full list of connection types, language model providers and auth providers. Only the github connection type appears in the example. If your repositories live on a host whose connection type is not documented there, you find out after installing.

## Sourcebot compared with Sourcegraph and with plain ripgrep

The most common comparison is Sourcebot versus Sourcegraph, and the difference is deployment model rather than feature list. Sourcegraph has historically been the reference implementation of cross-repository code intelligence, with a hosted offering and a self-hosted enterprise edition. Sourcebot's pitch is narrower and more literal: self-host it, point it at your connections, run it. The README's own framing is "Self Host" next to a public demo, and the deploy path is a compose file plus a JSON config. If you want a vendor to operate the index, Sourcebot is the wrong shape.

The other comparison is against the tools already on the machine. ripgrep searches a working copy fast and needs no server, no Postgres, no Redis and no index. What it cannot do is goto definition across repositories, because it has no symbol graph, and it cannot answer a natural-language question with citations. Sourcebot trades operational weight for those two capabilities. A single-repository team with one code host gets very little from that trade.

## Who should adopt Sourcebot, and what to check first

Adopt it if you have two or more code hosts and a genuine cross-repository navigation problem, and if running Postgres 16, Redis 8 and a Go indexer alongside a Next.js app is within your operational comfort. The compose file pins postgres:${POSTGRES_VERSION:-16} and redis:${REDIS_VERSION:-8}, so the defaults are current major versions and the variables let you override them.

Do not adopt it if you want a managed service, if your repositories already sit behind one vendor whose search is adequate, or if you cannot read LICENSE.md and accept its terms. The fair-source topic and the NOASSERTION licence field mean the licence question comes before the technical one for commercial use.

Verify the connection type for each host you intend to index against the config file documentation, since only github appears in the README example. Generate real secrets rather than leaving the compose placeholders, and decide on telemetry before first start by setting SOURCEBOT_TELEMETRY_DISABLED. The last push to the repository was on 2026-09-23 and the most recent release listed is v5.1.14 from 2026-09-17, so the project is moving, but the deployment documentation is thinner than the feature list.

## Conclusion

Adopt Sourcebot if you have repositories spread over several code hosts and you want one search box plus goto-definition and find-references that span all of them, and if you can run Postgres, Redis and a Zoekt indexer yourself. Do not adopt it if you need a hosted service with no infrastructure, or if your repositories are already consolidated behind a single vendor's search. Before committing, verify three things in your own environment: that the connection type for each host you use is documented in the config file reference, that you have generated real values for AUTH_SECRET and SOURCEBOT_ENCRYPTION_KEY rather than leaving the defaults, and that your Postgres and Redis volumes are backed up, since the config file alone does not reconstruct an index.

## FAQ

### What is Sourcebot?

Sourcebot is a self-hosted tool that helps you understand your codebase. It provides code search and navigation across repositories and branches regardless of where they are hosted, plus a natural-language question interface called Ask Sourcebot that answers with inline citations.

### What are some alternatives to Sourcebot?

Sourcegraph is the closest comparison, and the difference is deployment model: Sourcebot is self-hosted via Docker Compose with a JSON config file, while Sourcegraph has historically offered a hosted product alongside a self-hosted edition. Plain ripgrep is the lighter alternative, but it has no symbol graph for goto definition and no natural-language answers.

### How do you install Sourcebot?

Download docker-compose.yml from the repository, create a config.json in the same directory that defines at least one connection, update the placeholder secrets marked CHANGEME, and run docker compose up. The application is then available at http://localhost:3000.

### What is Sourcebot?

It is a self-hosted code intelligence tool that indexes repositories from multiple code hosts. The README describes it as a tool that helps you understand your codebase, with code search, code navigation and a natural-language Ask Sourcebot interface.

### How does Sourcebot compare with Sourcegraph?

No head-to-head comparison appears in the README. What can be said is that Sourcebot is self-hosted through Docker Compose and a JSON config file, whereas Sourcegraph has historically been the reference implementation of cross-repository code intelligence with both hosted and self-hosted editions.

## Sources

- [Issues](https://github.com/sourcebot-dev/sourcebot/issues)
- [Project website](https://sourcebot.dev)
- [README](https://github.com/sourcebot-dev/sourcebot/blob/main/README.md)
- [Releases](https://github.com/sourcebot-dev/sourcebot/releases)
- [sourcebot-dev/sourcebot on GitHub](https://github.com/sourcebot-dev/sourcebot)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sourcebot-dev-sourcebot