Quickstart

This quickstart is the common path across Docker, Terraform, and AWS. Choose the runtime first, then validate the same product workflow: sign in, connect GitHub, index one repository, and call ctx_advisor.

1. Choose how you will run ctx|

For a local Compose evaluation, copy the environment template and set at least a stable auth secret, public URL, and model credentials:

cp docker-compose.env.example .env
# edit AUTH_SECRET, AUTH_BASE_URL, CTXPIPE_PUBLIC_APP_URL,
# MODEL_PROVIDER, and the matching model credentials
pnpm start

pnpm start runs the Compose deploy profile, including migrations, backend, UI, worker, codesearch, Postgres, and FalkorDB. Telemetry stays off until you set OTEL_EXPORTER_OTLP_* to your own collector.

2. Verify the deployment boundary

Before adding a source:

• GET {AUTH_BASE_URL}/.status returns an OK status.
• The app opens through AUTH_BASE_URL, not the private UI service.
• Sign-in works with at least one configured method.
• Backend and worker can use the configured model provider.
• Postgres and the graph database are healthy.

See Authentication for the auth secret, origin, SMTP, and optional social providers.

3. Create your GitHub App and index one repository

Open Connectors → Add connection → GitHub. The self-hosted wizard guides an operator through creating a deployment-owned GitHub App with connection-specific callback and webhook URLs.

Follow Self-host GitHub, install the App on a narrow repository scope, then choose one repository under Repositories → Select repositories. Wait until it reaches Indexed.

4. Connect an MCP client

Use the CLI with your deployment URL:

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

Or configure the remote endpoint manually:

https://ctx.example.com/mcp?orgSlug=your-org-slug

The client should complete OAuth against your deployment. Access is not automatic merely because the URL exists; the signed-in user must belong to the requested organization.

5. Prove the complete loop

Ask the agent explicitly to use ctx|:

Use ctx_advisor before planning. Identify the relevant architecture,
standards, and source files, and label what still needs code verification.

You are ready to invite a team when:

• ctx_advisor returns an organization-scoped answer,
• that answer identifies useful source paths,
• a repository retry succeeds,
• backups and logs are configured,
• and your rollback procedure matches the deployment path.

Related setup