install.md

Install

Source: https://www.omnigraph.dev/docs/getting-started/install

macOS and Linux

curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph/main/scripts/install.sh | bash

The installer downloads a release archive, verifies its SHA-256 checksum, and installs the binaries in ~/.local/bin.

Prebuilt archives support Linux x86_64 and arm64, macOS arm64, and Windows x86_64. The Linux archives need glibc 2.39 or newer, as on Ubuntu 24.04 and Debian 13. Build from source on other platforms, including Intel macOS.

Homebrew is also supported:

brew tap ModernRelay/tap
brew install ModernRelay/tap/omnigraph

macOS signing and Keychain access

New macOS release archives are signed with EQTR INC's Developer ID and notarized by Apple, on both stable and edge channels. The CLI keeps the signing identifier com.modernrelay.omnigraph across updates so Keychain can recognize the new executable as the same application.

When moving from an older ad hoc signed build, macOS may ask you once to authorize the signed CLI to access an existing credential. Signing does not grant access to an item you have not authorized. Source and Nix builds use their own local signing identity and do not inherit release trust.

The release remains a tarball of three executables. Apple's notarization ticket is checked online: a ticket cannot be stapled to a standalone CLI binary or a tarball. A release can be published before Apple finishes notarizing it; its binaries count as notarized once Apple accepts the submission. Until then, macOS may refuse to open a copy downloaded with a web browser. The install script downloads with curl, which does not mark files for that check. Older published archives are unchanged.

Nix

The repository's flake builds the three release programs from source with the pinned Rust toolchain, the same packages and features as the release archives, on Linux x86_64 and arm64 and macOS arm64:

nix build github:ModernRelay/omnigraph
nix run github:ModernRelay/omnigraph -- version

Pin a commit or a release tag that carries the flake with github:ModernRelay/omnigraph/<ref>. A build of a clean checkout reports its commit; it reports no release channel.

Windows

powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr -UseBasicParsing https://raw.githubusercontent.com/ModernRelay/omnigraph/main/scripts/install.ps1 | iex"

Binaries are installed in %USERPROFILE%\.local\bin.

Release channels

The default is the latest stable release, and the installer prints its tag before downloading. Only when no stable release publishes the platform's archive (HTTP 404) does it fall back to edge, and it says so; a network or server failure stops the install instead of switching channels.

Edge builds are prereleases built once a day from the tip of main, after its whole CI run passes, when main has moved since the last one. Each is published as its own release, edge-<commit date>-<commit> (for example edge-20261016-9c2b367), whose files never change; the rolling edge release always holds the newest one. The 30 newest edge builds are kept, and so is the newest build of every storage format they no longer cover, since that build can still export a graph written at that format. To install the newest:

curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph/main/scripts/install.sh \
  | RELEASE_CHANNEL=edge bash
iwr -UseBasicParsing https://raw.githubusercontent.com/ModernRelay/omnigraph/main/scripts/install.ps1 -OutFile install.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 -ReleaseChannel edge

To deploy an edge build, pin it by its tag, so every machine installs the same binaries and you can return to them: VERSION=edge-20261016-9c2b367 on macOS/Linux or -Version edge-20261016-9c2b367 on Windows.

Each edge build is also a container image with the same tag, modernrelay/omnigraph-server:edge-20261016-9c2b367 on Docker Hub and ghcr.io/modernrelay/omnigraph-server:edge-20261016-9c2b367, holding that build's Linux x86_64 binaries on Debian trixie. The edge image tag follows the rolling edge release; latest stays on the newest stable release. Pin a deployment to the image's digest, which the run's summary lists. Provenance is attached to the GHCR digest; do not use a Docker Hub manifest digest to verify that attestation. GHCR access may require registry authentication; Docker Hub is the public pull channel. See container verification.

Read the build's release description before pointing it at a graph that a stable release must still read. It lists the storage format the build writes and the HTTP contract it speaks next to the latest stable release's. A branch the build writes to is left at the build's storage format, and a stable binary refuses a format newer than its own, so test on a copy of the graph or back it up first (upgrades). A client and a server must speak the same HTTP contract.

Install a specific stable tag with VERSION=v0.14.0 on macOS/Linux or -Version v0.14.0 on Windows. Set INSTALL_DIR or -InstallDir to choose a different destination.

Documentation on main may describe behavior newer than the latest stable binary. Check omnigraph version and the release notes.

Client compatibility

Upgrade the CLI, server, and HTTP integrations together. OmniGraph 0.14 requires HTTP contract 0.14; the npm 0.13.0 clients are not compatible with it. Both @modernrelay/omnigraph@0.14.0 and @modernrelay/omnigraph-mcp@0.14.0 are published on npm. Install the 0.14.0 clients alongside the 0.14 server; see the SDK release. For an existing deployment, follow the 0.13 → 0.14 checklist, including configuration and command replacements.

You can use the released CLI, the HTTP API, or the server's built-in MCP endpoint and CLI stdio bridge without either npm package. The MCP protocol has its own negotiation; refresh cached tool schemas when upgrading a client.

Build from source

Install the Rust stable toolchain and the Protocol Buffers compiler (protoc), then:

RUSTFLAGS= cargo build --release --locked \
  -p omnigraph-cli \
  -p omnigraph-server \
  -p omnigraph-azure-admission

The empty RUSTFLAGS replaces the workspace .cargo/config.toml build flags, which exist for the development test suites; release binaries build without them.

Or use the source installer:

curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph/main/scripts/install-source.sh | bash

Installed programs

Release archives contain:

The admission utility's inspect, break, and help commands are available on Windows. Its child-supervision run mode is supported only by the Unix deployment images used for the Azure reference topology.

Verify

omnigraph version
omnigraph-server --help
omnigraph-azure-admission --help

omnigraph version reports what the binary itself speaks, without opening a graph or contacting a server. For example, building the v0.14.0 source tag without release metadata prints:

omnigraph 0.14.0
internal-schema 16 (serves v14 to v16)
http-contract 0.14

omnigraph version --json also reports the machine-readable CLI protocols:

{
  "version": "0.14.0",
  "channel": null,
  "commit": null,
  "http_contract": "0.14",
  "protocols": { "studio": 1, "target": 2, "credential": 2, "access": 2 },
  "internal_schema": {
    "writes": 16,
    "serves": [14, 16]
  }
}

An edge build reports a SemVer pre-release of the package version, such as 0.15.0-edge+9c2b367. Edge builds are published only while the package version is above the latest stable release, so an edge version sorts after every published stable release and before the release it precedes. channel is stable or edge for a GitHub release archive and null for any other build. commit is the commit a packaged build was compiled from; a plain source build reports it as null and prints no commit line. The server reports the same commit as source_version on GET /healthz.

http_contract is the Omnigraph-Http-Api value the CLI sends. A server accepts only an exact match and returns its own value on every response, including HEAD /healthz (HTTP contract). When several CLIs are installed, for example one in ~/.local/bin and an older one from Homebrew, choose by this field, not by the package version. protocols.target and protocols.credential identify compatible generations of operator configuration/target administration and credential commands. Both are 2 for profiles, targets with one inline auth provider, and credential sources. Match these numbers exactly when selecting a CLI for those contracts; they are independent of the operator document's version: 1. Protocol 1 was published with multiple incompatible 0.14 edge grammars, so that number alone cannot select one of them. Use protocol 2 for the current format. An incompatible change to either contract requires its discovery number to change. protocols.access identifies the omnigraph access --json shape: protocol 2 uses actor_id in place of protocol 1's actor. protocols.studio identifies the Studio link, studio --json, and the home and binding digests target inspect --json reports for checking a link.

internal_schema.writes is the storage-format stamp of a graph this binary creates, the highest it writes, and internal_schema.serves is the inclusive range, lowest first, that normal open accepts; snapshot --json reports a graph's own stamp as internal_schema_version. omnigraph --version (-v) prints only the first line.

Release archives from v0.14.0 on, and every edge-<date>-<commit> build, carry a build provenance attestation. When the GitHub CLI (2.49 or later) is installed and signed in, both installers verify it after the checksum and refuse an archive that fails; otherwise they say the provenance was not checked. VERIFY_ATTESTATION=require refuses to install without the check, VERIFY_ATTESTATION=off skips it. An explicitly requested VERSION older than v0.14.0 has no attestation and installs with a warning. To check an archive yourself:

gh attestation verify omnigraph-linux-x86_64.tar.gz --repo ModernRelay/omnigraph

The container image carries the same stamp from v0.14.0, and its GHCR digest carries the attestation:

docker run --rm --entrypoint /usr/local/bin/omnigraph \
  modernrelay/omnigraph-server:<tag> version
gh attestation verify oci://ghcr.io/modernrelay/omnigraph-server:<tag> \
  --repo ModernRelay/omnigraph

Continue with the quickstart.