getting-started.md

stage	Analytics
group	Knowledge Graph
info	To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
description	Enable Orbit Remote on GitLab.com and run your first query.
title	Get started with Orbit Remote

{{< details >}}

• Tier: Premium, Ultimate
• Offering: GitLab.com
• Status: Beta

{{< /details >}}

{{< history >}}

• Introduced in GitLab 18.10 with a feature flag named knowledge_graph. Disabled by default. This feature is an experiment.
• Changed to beta in GitLab 19.1.

{{< /history >}}

[!flag] The availability of this feature is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.

Prerequisites

• Owner role on the top-level group you want to enable Orbit on

Orbit indexes top-level groups only. Subgroups and projects inherit indexing automatically.

Step 1: Enable Orbit

1. On the left sidebar, expand Your Work.
2. Select Orbit > Configuration.
3. Find your top-level group in the Indexes list.
4. Toggle Enable.

Orbit begins indexing immediately. Initial indexing takes a few minutes for small groups and up to 30 minutes for groups with thousands of projects.

Check indexing status at any time:

glab orbit remote status

Step 2: Run your first query

Orbit Remote exposes the same graph through three surfaces. Pick the one that matches who's querying:

Method	Best for	Setup	Billing
GitLab Duo Agent Platform	End users in the GitLab UI	None	Zero-rated
MCP	Claude Code, Codex, other AI agents	One-time agent config	GitLab Credits
REST API	Scripts, dashboards, custom tooling	API token	GitLab Credits

GitLab Duo Agent Platform (no setup required)

Orbit is wired into GitLab Duo Agent Platform. The GitLab Duo Agent, Planner Agent, Security Analyst Agent, Data Analyst Agent, CI Expert Agent, and Developer Flow call Orbit's query_graph and get_graph_schema tools automatically when a question is best answered by graph traversal. No tool selection or configuration required.

For example, file a work item asking to rename the deploy_user method. The Developer Flow uses Orbit to identify every service that calls it, then drafts an MR that updates each one.

GitLab Duo queries are zero-rated and do not consume GitLab Credits.

MCP (Claude Code, Codex, other agents)

See Use Orbit via MCP for setup. Once configured, you have two tools: query_graph and get_graph_schema.

Install the Orbit skill for AI agents

The Orbit skill gives your AI agent query recipes, DSL guidance, and troubleshooting so it writes correct Orbit queries on the first attempt:

glab skills install --global orbit

See Set up AI coding agents with the Orbit skill for project-scoped install, update instructions, and what the skill contains.

REST API

Replace your-group with the top-level group path you enabled Orbit on. The full_path filter scopes the query so it passes Orbit's selectivity validation.

curl --request POST \
  --header "Authorization: Bearer <your_token>" \
  --header "Content-Type: application/json" \
  --data '{
    "query": {
      "query_type": "traversal",
      "node": {
        "id": "p",
        "entity": "Project",
        "columns": ["name", "full_path"],
        "filters": {
          "full_path": {"op": "starts_with", "value": "your-group/"}
        }
      },
      "limit": 10
    },
    "format": "raw"
  }' \
  "https://gitlab.com/api/v4/orbit/query"

What to try next

• What Orbit indexes - understand coverage before writing queries
• Schema reference - explore the 28 node types and their properties
• Cookbook - copy-paste queries for common use cases
• Get started with Orbit Local - query a local repository offline