Getting oriented

How RepoQL runs

RepoQL runs a host beside the source it indexes. Your agent connects to that host to search, read, and query the repository.

For local development, the host runs on your machine and indexes your workspace. It stays available between tool calls and maintains the index as files change. A team can also run a host on shared infrastructure and connect agents remotely.

Your agent and the host have different jobs

Your agent decides what to investigate and makes tool calls. The host maintains the parsed index and answers those calls. MCP connects an agent to the tools; the rql CLI provides commands for a terminal or script. Both use the host’s repository data.

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

RepoQL hostAnswers from its maintained index

Workspace and imported sourcesFiles, declarations, and supported relationships

The host maintains the index independently of an individual agent conversation.

Working on your own machine

Install the native rql binary and connect it to your coding agent using the setup guide. There is no separate language runtime or container required for this setup. The host uses your designated workspace and its imported sources.

Clients connected to the same host share that index. A new conversation can use the existing data, while a change to a file causes the relevant indexing work to run again. Check the response’s readiness information when querying during an initial index or a large update.

A shared host can keep repositories available to teammates, hosted agents, and CI. The rql uplink service opens an outbound connection to RepoQL’s gateway. Remote clients use the instance’s authenticated URLs; they do not need an inbound connection to the machine running the host.

The member endpoint provides read access. The admin endpoint provides management access, including imports. The host needs its own instance credential and credentials for any private repositories it imports.

The repository and index stay on the host’s storage, but tool requests and results pass through the gateway to the caller. Those results can contain source code. Remote access therefore changes who can receive content, even though indexing remains on your infrastructure.

Reviewing with shared context

A reviewing agent needs the branch being changed and the systems that depend on it. Run a RepoQL host inside the CI job to index the checkout, including its captured concepts and any coverage or static-analysis results you supply. Connect the agent to the shared host through uplink to investigate other repositories and their requirements.

The animation shows the same review with two scopes: first the checkout and its checks, then the additional sources available through uplink.

The job’s host provides the proposed change. The shared host provides the surrounding system. Together, they let your reviewing agent trace a changed contract to a downstream consumer and explain which requirement the change would break.

Cloud processing is a separate choice

Local indexing and cloud-assisted search are different parts of the system. Parsing, source reads, local graph queries, git inspection, and local semantic search can run without a cloud account. Higher-quality cloud embeddings and reranking send selected content for processing. Generated explanations require cloud inference.

A local host can use cloud services, and a remote host still does its own indexing. Imports also contact their source servers. Your data describes these flows, usage records, and the controls available to you.

Operational reference

Setup	What to plan for
Local workspace	Use the installation guide and the host status command to check the selected repository.
Container	Mount the source or import it into the container. Persist the host’s state if you want to retain the index across replacements.
Uplink instance	Provide an instance credential, outbound HTTPS/WSS access, and access to import sources.
Uplink replacement	Run one replica per instance credential. Stop the previous replica before starting its replacement.
Persistent uplink data	Mount `/workspace` to retain the index and managed imports. The credential is separate from this data.

Container configuration and platform deployment instructions are in the installed manual. They include secret-file permissions, readiness probes, private-repository access, and how to verify the remote connection.

Further reference

In the installed manual: help:///hosting/container.md, help:///hosting/uplink.md, help:///commands/host.md.