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	Pick an access method and build your first local Orbit graph.
title	Get started with Orbit Local

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
• Status: Beta

{{< /details >}}

{{< history >}}

• Introduced in GitLab 19.0 as an experiment.
• Changed to beta in GitLab 19.1.

{{< /history >}}

Orbit Local runs on your machine. Install the orbit binary, pick the access method that matches how you work, then run your first query.

Install

Install the orbit binary directly with the one-line installer, or through the GitLab CLI (glab) if you already use it.

On Linux, the installer uses the glibc archive by default and automatically selects the fully static musl archive on musl-based distributions like Alpine. To force the static Linux archive, pass --libc musl.

{{< tabs >}}

{{< tab title="macOS and Linux" >}}

curl -fsSL "https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/main/install.sh" | bash

To explicitly install the static musl binary (e.g. on a glibc system):

curl -fsSL "https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/main/install.sh" | bash -s -- --libc musl

Open a new terminal, then verify:

orbit help

{{< /tab >}}

{{< tab title="Windows" >}}

irm https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/main/install.ps1 | iex

Open a new terminal, then verify:

orbit help

{{< /tab >}}

{{< tab title="GitLab CLI (glab)" >}}

If you already have glab installed:

glab orbit local --install

Verify:

glab orbit local help

See the glab orbit local reference for details.

{{< /tab >}}

{{< /tabs >}}

Pick an access method

Method	Best for	Setup
The Orbit CLI (orbit)	Direct CLI use, scripting, indexing tasks	One-line installer or glab orbit local --install
The GitLab CLI (glab)	Anyone already using glab	glab orbit local --install
MCP	Claude Code, Codex, and other AI agents	claude mcp add orbit-local -- orbit mcp serve

All three read the same local graph. Orbit Local is queried with DuckDB SQL; the structured JSON query DSL is Orbit Remote only.

60-second quickstart

Note

glab orbit local wraps the managed orbit binary. The binary downloads, is checksum-verified, and stays up to date on first use. Requires glab 1.94 or later. To run the binary directly instead, see Use the orbit CLI directly.

Index a repository and inspect what Orbit found:

glab orbit local index /path/to/your/repo
glab orbit local schema

That builds a local DuckDB graph at ~/.orbit/graph.duckdb and prints every table and column in it: gl_definition, gl_file, gl_directory, gl_imported_symbol, gl_edge, and the _orbit_manifest bookkeeping table.

Next:

• Run a real query: Use Orbit Local with glab.
• Wire it into your AI agent: run glab orbit setup to install the Orbit skill, or connect via MCP.
• Browse the table layout: Schema reference.

Billing

Orbit Local does not consume GitLab Credits. All processing is local.

What to try next

• What Orbit Local indexes - language and coverage scope.
• Schema reference - the four node types in the local graph.
• Cookbook - copy-paste queries (code-only ones apply to Local).
• Get started with Orbit Remote - query your full GitLab instance.