Skip to main content

Quick start

Sign in to a deployed CodeGraph instance, grant project access, import a repository, check its CPG, and connect a local MCP client.

Getting Started

Use this path after an administrator has deployed CodeGraph and given you the UI and API URLs, an account, and project-group access. For a new server, follow the installation guide first. Replace <UI_URL> and <API_URL> with your own instance addresses; the API URL does not include /api/v1.

1. Check that the instance is ready

Sign in at <UI_URL>/dashboard/login; the project catalog is at <UI_URL>/dashboard/projects. Check <API_URL>/api/v1/health/ready. The REST schema is at <API_URL>/api/docs (Swagger UI) or <API_URL>/api/openapi.json (OpenAPI JSON).

Administrator: create an account and grant access

If you need an account, the administrator first obtains a token from POST /api/v1/auth/token with username and password, then finds an existing group ID using GET /api/v1/groups. With Authorization: Bearer <admin-access-token>, create the user at POST /api/v1/admin/identity/users:

{
  "username": "engineer.one",
  "role": "analyst",
  "tenant_id": "<GROUP_ID_FROM_GET_GROUPS>",
  "change_reason": "Create a personal engineering account"
}

tenant_id records the administrative action context in the audit log. Grant project access with the separate access request below. Save the returned user id for the {user_id} path parameter. Give the returned temporary_password to the user through a secure channel. analyst suits most developers; reviewer has additional review and approval permissions. viewer is read oriented and admin administers the instance. After importing a project, use its id from GET /api/v1/projects to grant access with PUT /api/v1/admin/identity/users/{user_id}/access:

{
  "tenant_id": "<GROUP_ID_FROM_GET_GROUPS>",
  "change_reason": "Grant access to the selected project",
  "assignments": [{
    "group_id": "<GROUP_ID_FROM_GET_GROUPS>",
    "role": "editor",
    "project_scope_mode": "selected",
    "allowed_project_ids": ["<PROJECT_ID_FROM_GET_PROJECTS>"]
  }]
}

editor is a group role, distinct from the system role. Group roles are viewer, editor, and admin. The PUT replaces all assignments: before changing an existing user, read GET /api/v1/admin/identity/users/{user_id}/access and retain the required entries.

After granting access, repeat GET /api/v1/admin/identity/users/{user_id}/access and verify the editor role, selected mode, and selected project ID. Then sign in as the engineer and open the project catalog.

2. Select or import a project

Open <UI_URL>/dashboard/repositories, select a configured Git provider, and import a repository. Then check <UI_URL>/dashboard/projects. If no provider is configured, follow the REST and server CLI examples. Do not put credentials in the repository URL.

CPG (Code Property Graph) records code elements and their relationships. The project listing shows registered projects. Check the import job and CPG freshness first; refresh a stale, pending, or failed graph before relying on the analysis.

3. Run a first task

For the first audit, an administrator connects to the Ubuntu server over SSH, changes to the CodeGraph installation directory, and runs the command below. Get the CPG database path from the configured project; the API container must see the source path. This produces a deterministic JSON report without an LLM conclusion:

sudo docker compose -f docker-compose.yml exec -T api python -m src.cli audit \
  --db '<CPG_DB_PATH>' --source-path '<PROJECT_SOURCE_PATH>' \
  --profile standard --format json --skip-llm-conclusion --skip-persistence \
  --output '<AUDIT_OUTPUT_PATH>'

Replace all three placeholders with paths inside the API container. The output directory must exist and be writable. --skip-persistence prevents report persistence and automatic CPG refresh; it still writes the requested JSON file. If the command returns audit_cpg_refresh_required, refresh the project through the approved import workflow and retry the same command with its current graph.

Check the report, source revision, and analysis limitations. See the CPG audit guide for interpretation. Then choose a task with an observable result, for example:

  • find the entry points for a component;
  • inspect the impact of changing a named symbol;
  • review a bounded commit range;
  • explain a dependency path and cite its source locations.

Start with one component or a commit range. Check that the response names the selected project and cites its source files. Check the graph’s freshness and data availability when interpreting the result.

4. Connect a client and your project documentation

Install Codex CLI or an Agent Plugins compatible client on Windows, macOS, or Ubuntu. Get the MCP address and client package from your instance administrator. For the published remote service, follow the OAuth and MCP guide. After sign-in, call the read-only codegraph_runtime_stack_status_get tool with empty arguments:

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"codegraph_runtime_stack_status_get","arguments":{}}}

Send this request through an initialized, authenticated MCP session. Check tools/list in the configured connection first. If the tool is unavailable in its active profile, ask the administrator for a connection that exposes runtime status. The response lists agent adapters, runtime pools, sandbox profiles and managed sessions. Inspect health.status and health.worker_health for the configured adapters. Check the selected project’s import job and CPG freshness for graph readiness, as described in step 2.

Open a local checkout of the selected project. Its AGENTS.md should point to the actual documentation location. A useful starting layout is README.md for purpose and setup, and docs/ for architecture, API, operations, and checks. If your team uses OpenSpec, point to its existing specifications directory. For a small fix, create a named lightweight task with an owner, scope, and completion criterion. For a feature, prepare requirements and acceptance criteria in a full task under your team’s process.

For document search and long-term memory, ask the administrator to enable OpenViking using the configuration guide. Source-only audit does not require it.

5. Explore the bundled demo

To see a guided workflow without importing customer documents, open /dashboard/onboarding-research and select a demo preset. Demo data explains the interface; use the imported project and its current CPG for repository-specific results.

Configure automatic project checks

After importing the repository, connect its events. A push webhook supplies new commits for CPG updates; pull request or merge request events start review preparation. Follow the guide for your Git server:

  • GitHub: repository connection, webhooks and pull request review.
  • GitLab: repository connection, webhooks and merge request review.
  • GitVerse: webhooks, synchronization and pull request review publication.
  • SourceCraft: repository coordinates, webhooks and merge request review.

Choose events for the branches you use and verify a test push: wait for the synchronization job, then compare the CPG commit with the repository commit. For a PR/MR, inspect the review result and its publication in the target request.

Architecture control explains how to describe components and allowed dependencies in YAML, validate rules and apply them when checking changes.

To run checks regularly, configure automatic project audits: choose the cadence, time zone, service account and missed-run policy. Verify the first run and its saved report.

If the first run fails

  • No project is visible: ask the administrator to check tenant and project access.
  • CPG is stale or missing: request or wait for project refresh before repeating the analysis.
  • The result is blocked: preserve the reason and session identifier for support.
  • The result lacks source evidence: narrow the question and verify the selected project.

Next: Installation · Configuration · Scenario catalog

Report a documentation issue