omicron: the control plane for Oxide Rack, written in Rust

A control plane that only runs for real on Oxide's own OS

This repository houses the work-in-progress Oxide Rack control plane, and the README is unusually direct about what that means.

Omicron is open-source, but the project is pretty focused on our own goals for the foreseeable future and not able to help external contributors, with a pointer to CONTRIBUTING.md for more information. There is no GitHub release history for the project, so the version is tracked in the repository itself.

The operational split is the first thing to understand, and the README states it in two paragraphs. Omicron has two modes of operation, simulated and non-simulated. The simulated version allows the high-level control plane logic to run without actually managing any sled-local resources, and this version can be executed on Linux, Mac, and illumos. That mode is provided for development and testing only.

The non-simulated version actually manages sled-local resources, and may only be executed on hosts running Helios. That mode is the one that will be used in production.

So a developer who clones this can run the entire control plane logic on a laptop, and a production deployment runs on the operating system Oxide built for the rack. The consequence for a reader is that the repository is a design document as much as a product, and the simulated mode is what makes it readable without a rack.

The code is Rust, the licence is MPL-2.0, the last push was on 2026-10-20, and the top level listing shows a workspace of well over a hundred packages, from `api_identity` and `bootstore` through `gateway`, `installinator`, `internal-dns`, `key-manager`, `ledger`, `nexus` and `oximeter` to `sled-agent-client` and `wicketd-client`.

API documentation generated from the implementation, not the other way round

The documentation approach is the part of this repository that generalises best, and it is worth describing precisely because it is unusual.

The public API docs at docs.oxide.computer/api are automatically generated for the public, externally-facing API, based on the OpenAPI spec that itself is automatically generated from the server implementation. So the direction of travel is implementation to spec to docs, not the other way round, and a doc that disagrees with the code is a doc that cannot be stale because the code produced it.

You can generate your own docs for either the public API or any of the internal APIs by feeding the corresponding OpenAPI specs, in the `./openapi` directory, into an OpenAPI doc generator. That matters for a control plane with several API surfaces, because the public one is what partners and integrators use and the internal ones are what the components talk to each other with.

The technical design and development docs are collected at oxidecomputer.github.io/omicron, generated from the `./docs` directory and other docs throughout the repo, and the README suggests the control plane architecture page as a good place to start. For more design documentation and internal Rust API docs there is a separate generated Rust documentation site, which you can generate yourself with:

$ cargo doc --document-private-items

and the note that `--document-private-items` is configured by default, so you can actually just use `cargo doc`.

That configuration detail is a nice touch. By default a Cargo project documents only the public API of its library crates, and in a control plane where most of the interesting types are internal to the workspace, flipping that default on means the generated documentation covers the whole thing rather than the thin public surface.

The README also mentions RFDs, with RFD 48, Control Plane Requirements, named for readers with access to Oxide's internal design documents, and notes that they are not currently publicly available. The public documentation and the internal requirements are two different tiers, and the public tier is what an outside reader has to work with.

A workspace of a hundred packages, and how to work in it

The README calls Omicron a pretty large repo containing a bunch of related components, and links a document explaining why. It then gives practical advice, because the alternative is a developer waiting an hour for a build they did not need to wait for.

If you just build the whole thing with `cargo build` or `cargo nextest run`, it can take a while, even for incremental builds. Since most people are only working on a few of these components at a time, it is helpful to know about Cargo's tools for working with individual packages in a workspace.

The key tips are three. Use `cargo check` when you just want to know if your code compiles, because it is much faster than `cargo build` or `cargo nextest run`. When using Cargo's check, build, test or clippy commands, use the `-p PACKAGE` flag to only operate on a specific package, which often saves a lot of time for incremental builds. And when using the check, build or clippy commands, use `--all-targets` to make sure you are checking or building the test code too.

There is a fourth tip aimed specifically at editor users, because it solves a problem most people hit and few think to look for. Use `cargo.targetDir` to give rust-analyzer a target directory other than `./target` so it doesn't block you from running commands in the terminal. This uses extra disk space, and the README shows how to set it per editor, for example in Helix:

[language-server.rust-analyzer.config]
cargo.targetDir = true

The problem being solved is that rust-analyzer and the terminal both want the same target directory, and the language server's long-running analysis holds a lock that makes the terminal's cargo commands wait. Moving the language server's output elsewhere is the fix.

The worked example that follows is a good illustration of the intended workflow. Suppose you are working on changes to the Nexus database model, the `nexus-db-model` package located at `nexus/db-model` from the root. While you are actively writing and checking code you might run:

cargo check --all-targets

without any `-p` flag, which is pretty fast even on the whole workspace, and which also uncovers places where your changes have broken code that uses this package. If you are making big changes you might not want that right away, and you could choose to use `-p nexus-db-model` instead. Then, when you are ready to test, you start with the most specific package you have changed:

cargo nextest run -p nexus-db-model

then move up a level to the next package:

cargo nextest run -p omicron-nexus

and only when you are happy with things do you test everything.

The `all-targets` flag in the first command is doing real work there. Without it, a check that passes says nothing about the test code, and a change that broke a test helper would not be caught until you ran the tests.

The package list tells you what a rack control plane actually contains

The Cargo workspace membership list is the closest thing the repository has to an architecture diagram, and reading it is a reasonable way to understand the scope.

The names fall into recognisable groups. There are the client crates under `clients/`, one per service: `nexus-client`, `sled-agent-client`, `gateway-client`, `installinator-client`, `oximeter-client`, `clickhouse-admin-server-client`, `cockroach-admin-client`, `dns-service-client`, `ntp-admin-client`, `repo-depot-client`, `bootstrap-agent-lockstep-client`, `nexus-lockstep-client` and `wicketd-client` with its commissioning client. A `clients/` directory with a crate per downstream service is the shape of a system where each component talks to the others through typed clients rather than by reaching into each other's internals.

Then there are the service crates themselves, and the names hint at the data stack: `cockroach-admin` and `cockroach-metrics` for the CockroachDB administrative surface, `clickhouse-admin` for the ClickHouse side, `oximeter` for the metrics pipeline, `ntp-admin` for time synchronisation, `internal-dns` for the internal name service, `dns-server`, `gateway` and `gateway-api` and `gateway-types` for the external-facing side, `installinator` with its api and common packages for the install path, `key-manager` for key material, `ledger` for the durable record, `bootstore` for boot-time state, `certificates` for certificate handling, `nexus` and `nexus-config` for the central service, `api_identity` for identity, `ipcc` and `package/` and `packages/` for the package management surface, `passwords/` for credential handling, `generation-kinds` for the hardware generation model, `oximeter`, `end-to-end-tests/`, `live-tests/` and `parallel-task-set/`.

The dev-tools directory is the part that shows the project's working method. It is not a small set of scripts. There are `dev-tools/omicron-dev` and `omicron-dev-lib` for the development environment, `dev-tools/db-dev` and `ch-dev` and `crdb-seed` and `clickhouse-cluster-dev` for standing up the databases the system needs, `dev-tools/reconfigurator-cli` and `reconfigurator-exec-unsafe` and `reconfigurator-sp-updater` for reconfiguring a running system, `dev-tools/dropshot-apis` and `ls-apis` for generating API definitions, `dev-tools/oxlog` for the log format, `dev-tools/pins` for the pinned dependency set, `dev-tools/releng` for release engineering, `dev-tools/cert-dev` for certificate development, and `dev-tools/omicron-deployment-graph` and `repo-depot-standalone` for the deployment and repository tooling.

Reading that list tells you something the prose does not. A control plane of this size needs tooling to stand up its own dependencies, to regenerate its API surface, to reconfigure a live system safely, and to manage release pinning, and all of that tooling lives in the same workspace rather than in separate repositories. The `env.sh` file at the root and the `.envrc` for direnv are the entry points into that environment.

The infrastructure choices are visible too. `clickhouse-admin/` and `cockroach-admin/` and `oximeter/` mean the metrics and administrative data go to ClickHouse and CockroachDB, and `internal-dns/` and `dns-server/` mean name resolution is part of the system rather than a dependency on something else.

nextest, not cargo test, and a separate suite for deployed systems

The supported way to run tests is via cargo-nextest, and the README is blunt about the alternative: `cargo test` will not work for many of our tests, since they rely on nextest-specific features.

That is a real constraint on how you work in this repository, and it has a practical consequence for tooling. If you do not already have nextest installed, the README points at downloading a pre-built binary or installing it via your package manager, and nextest has pre-built binaries for Linux, macOS and illumos.

$ cargo nextest run

Nextest does not support doctests, so those run separately with `cargo test --doc`.

Tests can also be run inside a Falcon based virtual machine, described in the test-utils README, which is the way to exercise the parts of the system that need real operating system behaviour. And there is a separate live-tests suite that can be run by hand in a deployed Omicron system, which is a different category again: not a unit test but a check against a running rack.

The formatting and linting rules are simple and enforced in CI. You can format the code using `cargo fmt`, and the README says to make sure you run this before pushing changes because the CI checks that the code is correctly formatted. Clippy is run with `cargo xtask clippy`, and CI checks that code is clippy-clean. The `cargo xtask` mechanism is worth noting as a pattern, since the same mechanism is used for the library dependency check described below, so the project has one entry point for its own tooling rather than a Makefile with several targets.

The dependency hygiene check is the part with real engineering value. The project checks that certain system library dependencies are not leaked outside of their intended binaries via `cargo xtask verify-libraries` in CI. If you are adding a new dependency on an illumos or Helios library it is recommended that you update the allow list in `.cargo/xtask.toml` with where you expect the dependency to show up. The example given is that some libraries such as `libnvme.so.1` are only available in the global zone and therefore will not be present in any other zone.

That is a zone-aware dependency check, and it is the kind of thing that only matters on a system with zones, which is why it is worth reading even if you are not deploying an Oxide rack. The README explains how to inspect a compiled binary for what it requires by using `elfedit`.

Editorial conclusion

Adopt Omicron as a reference implementation if you are building a Rust infrastructure control plane, since the package layout, the OpenAPI-driven documentation and the cargo xtask tooling are worth reading. Do not adopt it as a dependency, because the project states it is focused on Oxide's own goals and is not able to help external contributors, and check first that you understand the split between simulated and non-simulated operation, since the version that manages real sled-local resources only runs on hosts running Helios.

Frequently asked questions

Official sources

1. Issues
2. License: MPL-2.0
3. oxidecomputer/omicron on GitHub
4. README