Getting oriented

How RepoQL runs

RepoQL runs a host beside your code. The host indexes it and keeps the index current as files change. Your agent connects to the host whenever it needs to look something up.

The host can run in three places. Most people start with the first.

Where the host runs	Who uses it
On your machine	You, and every agent session you open in that repository.
On your infrastructure, through Uplink	Your team: teammates’ agents, review bots, chat assistants and CI.
Inside a CI job	A review agent, looking at the change under review.

The agent asks, the host answers

Your agent decides what to investigate. The host keeps the index and answers its calls. Agents connect through MCP; the rql command gives you the same tools in a terminal or a script.

Your agent or terminalAsks for a search, a read or a query

RepoQL hostAnswers from the index it keeps current

Your code and imported sourcesFiles, declarations and the links between them

The host outlives any one conversation, so a new session starts with the index already built.

On your machine

Install the rql binary and connect it to your agent with the setup guide. It’s a single native binary: there’s no language runtime or container to install.

Every session you open in a repository shares that repository’s host, so a new conversation starts with the index already built. When a file changes, the host re-indexes what the change affects.

While the first index is being built, or after a large change, answers can be incomplete. Every response ends with the index’s readiness, so check it before treating an empty search as proof that something isn’t there.

Not every agent runs beside a checkout: a review bot, a chat assistant, a teammate asking from their phone. Uplink puts one RepoQL host, with your repositories and your team’s knowledge, within reach of all of them.

It connects out. rql uplink runs in a container on your infrastructure and opens one outbound connection to RepoQL’s gateway. There’s no inbound port, certificate or DNS to set up.
It has two doors. The gateway gives the host two stable URLs. The member door is read-only. The admin door can also import repositories and manage the host.
You choose who can use it. In the portal, grant access to the whole organization or to selected groups. People sign in through their browser; a CI pipeline exchanges its credential for a short-lived token.
Chat assistants can use it. A chat application that supports remote MCP connectors can connect once and ask about any uplink its user can access, with no local installation.

What leaves your infrastructure. The repositories and the index stay on the host’s storage. Tool requests and their results pass through the gateway to whoever asked, and results can contain source code. So Uplink changes who can receive your code, even though indexing stays on your infrastructure.

In a code review

A review agent needs two views: the change itself, and the systems that depend on it. Run a RepoQL host inside the CI job to index the checkout, with its concepts and any coverage or lint reports you give it. Connect the same agent to your team’s uplink to reach the other repositories and what they require.

The same review twice: first with only the checkout and its checks, then with the other repositories reached through Uplink.

Together, the two hosts let the review agent follow a changed contract to a service that depends on it, and say which of that service’s requirements the change would break.

What uses the cloud

Where the host runs and whether it uses cloud services are separate choices.

Local, with no account: parsing and indexing, reading source, SQL over the index, git history, and semantic search with a local embedding model.
Cloud, when you sign in: higher-quality embeddings and reranking, which send selected content for processing, and generated explanations, which need cloud inference.

An uplink host still does its own indexing, and imports contact the servers they fetch from. Your data describes what is sent, what is kept and the controls you have.

Running an uplink

Plan for	What it needs
Identity	An instance credential, issued in the portal or with `rql account instance issue`, passed to the container as a secret file.
Network	Outbound HTTPS and WebSocket access to the gateway, and to every source you import from.
Storage	A volume mounted at `/workspace` to keep the index and imports across restarts. The credential is kept separately.
Private repositories	Credentials for any private source the host imports.
Upgrades	One running container per credential. Stop the old one fully before starting its replacement; two on one credential keep displacing each other.

The installed manual has the full container setup, including secret-file permissions, readiness checks, and recipes for AWS, Google Cloud and Kubernetes.

Further reference

In the installed manual: help:///hosting/uplink.md for running an uplink, help:///hosting/shared-uplink.md for connecting a chat assistant, help:///hosting/container.md for a local container, and help:///commands/host.md for host commands.