Getting started

Quickstart

Deploy ctxpipe, set the public origin, and prove the loop from a source to an agent.

This quickstart is the same for each deployment path. Deploy ctxpipe. Then test the product loop: sign in, connect GitHub, and index one repository. Then search it from an agent with the MCP tools.

1. Deploy

For a Docker Compose evaluation, clone the repository and set the minimum values:

git clone https://github.com/ctxpipe-ai/ctxpipe.git
cd ctxpipe
cp docker-compose.env.example .env
# Set AUTH_SECRET, AUTH_BASE_URL, CTXPIPE_PUBLIC_APP_URL,
# MODEL_PROVIDER, and MODEL_PROVIDER_API_KEY.
pnpm start

pnpm start runs the Compose deploy profile. See Docker for what it starts and what to set before people depend on it.

For AWS, see AWS CDK. For Railway and Neon, see Terraform.

Use one stable HTTPS origin

The browser, auth, the API, connector callbacks, and MCP all use the public backend origin, AUTH_BASE_URL. Keep the other services private.

2. Check the deployment

Before you add a source, make sure that:

  • GET {AUTH_BASE_URL}/.status returns ok;
  • the app opens through AUTH_BASE_URL;
  • you can sign in with at least one method. See Authentication;
  • the backend and the worker can reach the model provider;
  • Postgres and the graph database are healthy.

3. Create your GitHub App and a Workspace

Open Connectors, select Add connection, then select Connect on the GitHub row. The wizard helps you create a GitHub App that your deployment owns. Follow Self-host GitHub. Then install the App on a few repositories.

Then create a Workspace, and link one code repository in its Settings. Wait until the repository shows Indexed.

4. Connect an agent

Run the CLI with the URL of your deployment:

npx ctxpipe init --base-url https://ctx.example.com

Or set up your client by hand with https://ctx.example.com/mcp. See Connect your agent. The client authorizes against your deployment. The signed-in user must be a member of each organization that the client reads.

5. Prove the loop

Ask the agent:

Use ctxpipe before you plan. Call list_workspaces, then search_knowledge and
search_code. Name the relevant architecture, standards, and source files, and
say what still needs a check in the code.

You are ready to invite your team when:

  • list_workspaces lists your organization and its Workspaces;
  • search_knowledge and search_code return useful refs;
  • a repository that you index again finishes;
  • backups and logs are in place;
  • you have a rollback procedure for your deployment path.