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, FalkorDB, and the optional telemetry 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