---
title: "Getting started"
description: "Install the complete Desk CLI, choose a server mode, and launch your first durable agent session."
---

The curl installer authenticates and activates a prebuilt versioned Desk release,
then makes the complete `desk` CLI immediately available on your existing `PATH`.

## Requirements

You need `/bin/bash`, a working `curl` with TLS trust, and the platform checksum
utility (`sha256sum` on Linux or `shasum -a 256` on macOS). The shell also checks
the standard `uname`, `mktemp`, `mkdir`, `chmod`, `rm`, and `wc` commands before
downloading release bytes. Supported release targets are:

- macOS x64 and arm64
- glibc Linux x64 and arm64, including WSL

Alpine and other musl systems are rejected before activation because Desk does
not publish a compatible application closure for them.

The installer does not invoke `apt`, `dnf`, `pacman`, `zypper`, `apk`, Homebrew,
npm, Bun, Python, tar, or a compiler. The release carries authenticated Node
22.23.1, Moor, native dependencies, and ripgrep under the Desk install root; it
does not replace global runtimes.

<Note>
  The generated shell authenticates a target-native bootstrap. The bootstrap
  validates manifest schema 3, downloads only the selected prebuilt application,
  Node, and Moor assets, verifies their complete closure, and activates them
  atomically. Desk resolves explicit `DESK_MOOR_BIN`, then an attested same-release
  `libexec/moor`, then an attested absolute `moor` on `PATH`.
</Note>

Agent CLIs (`codex`, `claude`, `opencode`, and optionally `qwen`, `kimi`, `grok`), `gh`, and GPU telemetry commands
are optional. Install only the integrations you intend to use.

## Install and start Desk

<Steps>
  <Step title="Install the CLI">
    ```bash
    curl -fsSL https://github.com/BrainyBlaze/desk/releases/latest/download/install.sh | bash
    command -v desk
    desk help
    ```

    The installer refuses a launcher directory outside `PATH` and refuses to
    overwrite an unidentified `desk` command. A successful install therefore
    makes `curl ... | bash && desk serve` valid in the invoking shell.
  </Step>

  <Step title="Start the default server">
    ```bash
    desk serve
    ```

    Plain `serve` launches the private Bun runtime and embedded UI. It binds to
    `127.0.0.1:5173` by default.

    ```bash
    desk serve --host 127.0.0.1 --port 5173
    ```

    <Check>
    Open `http://127.0.0.1:5173` and confirm that the Desk UI loads.
    </Check>
  </Step>

  <Step title="Create your first session">
    In the UI, open **Add session** and choose a session name, agent or command,
    and repository directory. Desk writes the session to
    `~/.config/desk/desk.yml` and owns its Moor lifetime.
  </Step>
</Steps>

## Choose the Vite development mode

Use Vite only when you are developing Desk or need source-level UI behavior:

```bash
desk serve --dev
```

The modes are explicit and fail closed. Plain `desk serve` never falls back to
Vite, and `desk serve --dev` never falls back to Bun. Host and port precedence is:
flags, then `DESK_HOST` / `DESK_PORT`, then `127.0.0.1:5173`.

## Authenticate optional integrations

Sign in through each tool's own CLI:

```bash
codex
claude
opencode
gh auth login
gh auth refresh -s project
```

Missing optional tools disable only their related subsystem.

## Operate a configured fleet

```bash
desk up --dry-run
desk up
desk status
desk attach <name|sessionId|resume>
desk capture <name|sessionId|resume> --lines 200
desk hooks install
```

`desk up` starts missing configured sessions without replacing running Moor
sessions.

## Upgrade, reinstall, or downgrade

Rerun the installer to resolve and install the latest release:

```bash
curl -fsSL https://github.com/BrainyBlaze/desk/releases/latest/download/install.sh | bash
```

Pin a binary-only release for an explicit install or downgrade:

```bash
version=v0.4.2
curl -fsSL "https://github.com/BrainyBlaze/desk/releases/download/$version/install.sh" | bash
```

A same-version run creates and verifies a new immutable instance instead of
modifying the active one. After activation, Desk retains the current and previous
instances for rollback.

Stores written by Desk v0.3.1 or older are not migrated by the current release.
Desk v0.3.2 is the last release that migrates them in place; a machine still on
v0.3.1 or older must boot v0.3.2 once against its store before upgrading
further. A newer Desk that meets an unmigrated store refuses it by name and
says so — see [Troubleshooting](troubleshooting.md).

## Uninstall the managed application

```bash
curl -fsSL https://github.com/BrainyBlaze/desk/releases/latest/download/install.sh \
  | bash -s -- --uninstall
```

Uninstall verifies Desk ownership before removing the launcher, releases, and
install metadata. It preserves `~/.config/desk`, projects, Moor
sessions, credentials, and optional host tools. To remove configuration too,
inspect it first and then delete it explicitly:

```bash
rm -rf ~/.config/desk
```

## Build from source

Contributors should use the same pins as CI: Node 22.23.1, npm 10.9.8, and Bun
1.3.14, plus `make` and a working C/C++ toolchain.

```bash
git clone https://github.com/BrainyBlaze/desk.git
cd desk
npm ci
npm run build:distribution
npm link
desk serve --dev
```

See [Distribution and deployment](/distribution-deployment) for the versioned
layout and release assets, and [Run Desk securely](/guide-deploy-securely) before
changing the bind address.

## Next steps

<Columns cols={2}>
  <Card title="Model a fleet" icon="layout-grid" href="/guide-create-agent-fleet">
    Configure projects, groups, sessions, layouts, permissions, and startup.
  </Card>
  <Card title="Use channels" icon="messages-square" href="/guide-channels-collaboration">
    Add agents to rooms, mention them, and inspect delivery diagnostics.
  </Card>
  <Card title="Understand configuration" icon="file-cog" href="/configuration">
    Learn the `desk.yml` manifest schema.
  </Card>
  <Card title="Troubleshoot setup" icon="wrench" href="/troubleshooting">
    Diagnose installer, PATH, server, and session failures.
  </Card>
</Columns>