# How to Set Up a Development Environment for Omarchy: Complete Developer Guide

> Set up your Omarchy development environment quickly. Link your system to local Git for live updates and testing. Get the complete developer guide now.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-19

---

**Omarchy provides a dedicated dev channel that links your running system to a local Git checkout, enabling live updates and testing without rebuilding the OS image.**

Setting up a development environment for Omarchy requires switching from the stable release channel to the **dev channel**, which routes all `omarchy-*` commands to a local clone of the source tree. This workflow, implemented in the `basecamp/omarchy` repository, leverages the **Mise** version manager and Docker to provide a full-stack development stack. By following the official file layout conventions documented in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md), you can edit source code and test changes immediately without repackaging the operating system.

## Install a Fresh Omarchy System

Before configuring the development environment, you must have a working Omarchy installation. Follow the official installation guide in [[`README.md`](https://github.com/basecamp/omarchy/blob/main/README.md)](https://github.com/basecamp/omarchy/blob/quattro/README.md) to install the base system.

Once installed, verify that the standard Omarchy menu functions by pressing **Super + Space** to open the launcher.

## Install Development Tools and Runtimes

Omarchy bundles a complete development stack managed by **Mise**. To install the runtimes:

1. Open the Omarchy menu (**Super + Space**) → **Install > Development**.
2. This single action installs Node.js, Bun, Deno, Go, Rust, Python, Java, Elixir, .NET, OCaml, Zig, Clojure, Scala, and Docker tooling.
3. Verify Mise is pre-installed by running:

```bash
mise --version

```

The Development tools configuration is documented in [[`manual/18-development-tools.md`](https://github.com/basecamp/omarchy/blob/main/manual/18-development-tools.md)](https://github.com/basecamp/omarchy/blob/quattro/manual/18-development-tools.md), which details how the system manages multiple language runties through the Mise shim.

## Switch to the Dev Channel and Link Your Repository

The dev channel redirects all Omarchy commands to use a local Git checkout instead of packaged binaries. This is the core mechanism for developing on the system itself.

Switch to the dev channel:

```bash
omarchy channel-set dev

```

Clone the Omarchy repository to your home directory:

```bash
git clone https://github.com/basecamp/omarchy.git ~/omarchy

```

Link the checkout to the running system using the `omarchy dev link` command:

```bash
omarchy dev link ~/omarchy

```

This command creates [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) and a `sudoers` drop-in file that ensures every `omarchy-*` command invoked on the system uses the live source code from `~/omarchy` rather than the packaged version. The implementation details are documented in [[`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md)](https://github.com/basecamp/omarchy/blob/quattro/docs/file-layout.md) and the entry point logic resides in [`bin/omarchy`](https://github.com/basecamp/omarchy/blob/quattro/bin/omarchy).

## Provision Your User Environment

After linking the repository, initialize your user environment to create necessary directories and symlinks:

```bash
omarchy provision-user --first-install

```

This command (defined in [[`install/user/all.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/all.sh)](https://github.com/basecamp/omarchy/blob/quattro/install/user/all.sh)) performs the following actions:

- Initializes per-user XDG directories.
- Creates symlinks for skill plugins.
- Generates migration markers for tracking state changes.

You only need to run this once per user account when first setting up the development environment.

## Running Tests and Development Sessions

With the dev channel active, you can start a hot-reloading development session:

```bash
omarchy dev layout

```

This launches a Quickshell layout that automatically reloads as you modify source files. For database-dependent development, use the Omarchy menu (**Super + Space**) → **Install > Development** to spawn Docker database containers.

To verify your changes against the test suite:

```bash
cd ~/omarchy
./test/all

```

The master test runner executes suites from [`./test/shell`](https://github.com/basecamp/omarchy/blob/quattro/test/shell), [`./test/cli`](https://github.com/basecamp/omarchy/blob/quattro/test/cli), and migration tests as documented in [[`docs/testing.md`](https://github.com/basecamp/omarchy/blob/main/docs/testing.md)](https://github.com/basecamp/omarchy/blob/quattro/docs/testing.md). Run this before committing to ensure your modifications do not break existing behavior.

## Summary

Setting up a development environment for Omarchy involves these key steps:

- Install development tools via the Omarchy menu to enable Mise and language runtimes.
- Execute `omarchy channel-set dev` to switch from stable to the development channel.
- Clone the repository to `~/omarchy` and run `omarchy dev link ~/omarchy` to create the [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) binding.
- Run `omarchy provision-user --first-install` to initialize user-specific directories and symlinks.
- Use `./test/all` to validate changes against the CLI, shell, and migration test suites.

## Frequently Asked Questions

### What is the Omarchy dev channel?

The dev channel is a runtime configuration that routes all `omarchy-*` commands to a local Git checkout rather than the system's packaged binaries. When you run `omarchy channel-set dev`, the system prepares to use live source code, and `omarchy dev link` creates the necessary [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) and `sudoers` configuration to make this redirection permanent.

### How do I verify Mise is installed correctly?

After enabling the Development section in the Omarchy menu, open a terminal and run `mise --version`. The Mise binary is pre-bundled with Omarchy and manages Node.js, Python, Rust, and other language runtimes through version-specific shims documented in [`manual/18-development-tools.md`](https://github.com/basecamp/omarchy/blob/main/manual/18-development-tools.md).

### Can I use a different directory than ~/omarchy for development?

Yes, you can clone the repository to any path. Simply substitute your custom path in the `omarchy dev link` command. For example: `omarchy dev link /path/to/custom/omarchy`. The linking mechanism updates [`/etc/omarchy.conf`](https://github.com/basecamp/omarchy/blob/main//etc/omarchy.conf) to point to whatever directory you specify.

### How do I run only specific test suites instead of the full suite?

While `./test/all` runs the complete validation, you can execute individual test components directly. Run `./test/shell` for shell plugin tests or `./test/cli` for command-line interface tests. Consult [`docs/testing.md`](https://github.com/basecamp/omarchy/blob/main/docs/testing.md) for the specific test organization and how to run migration-specific tests independently.