---
title: Overview
description: A headless Ubuntu server build of my dotfiles, with a shared Herdr session.
---

The headless [Ubuntu Server](https://ubuntu.com/server) build of my dotfiles. It is a cut-down copy of the [Omarchy desktop](https://dotfiles.timmo.dev/) setup with the terminal and service tooling only, and it hosts a [Herdr](/server/herdr/) session that other machines attach to. [GNU Stow](https://www.gnu.org/software/stow/) links each package into place, and a compiled `dot` CLI sets up, updates and checks the machine. Private machine details live in a separate overlay.

:::note[Work in progress]
This build is ahead of the real server. See the [server overview](/server/overview/) for what is still open.
:::

```bash
# Pull, refresh config, re-stow and rebuild
dot update

# Run the health checks and save a report
dot doctor
```

:::caution[Personal setup]
These docs and the public dotfiles are for reference. They are tuned for my machines and a private overlay that is not public, so installation is not recommended. Have your agents borrow the ideas you want instead.
:::

## How it fits together

<div style={{ display: "flex", flexWrap: "wrap", gap: "1.5rem", justifyContent: "center", margin: "1.5rem 0" }}>
  <figure style={{ margin: 0, width: "9rem", display: "flex", flexDirection: "column", alignItems: "center", textAlign: "center" }}>
    <img src="/illustrations/stow.svg" alt="" width="120" height="120" />
    <figcaption>Stow links the packages into place</figcaption>
  </figure>
  <figure style={{ margin: 0, width: "9rem", display: "flex", flexDirection: "column", alignItems: "center", textAlign: "center" }}>
    <img src="/logo-dark.svg" alt="" width="120" height="120" />
    <figcaption><code>dot</code> sets up and maintains the machine</figcaption>
  </figure>
  <figure style={{ margin: 0, width: "9rem", display: "flex", flexDirection: "column", alignItems: "center", textAlign: "center" }}>
    <img src="/illustrations/agents.svg" alt="" width="120" height="120" />
    <figcaption>Agents share skills and guidance</figcaption>
  </figure>
</div>

## Core

| Page | Why |
| --- | --- |
| [Getting started](/getting-started/) | Bootstrap the server |
| [Configuration](/configuration/) | Private overlay, packages, and tracked app config |
| [Distros](/distros/) | The desktop build and any others, with their own docs sites |
| [`dot` CLI](/dot/overview/) | Setup, sync, stow, doctor, and git helpers ([command reference](/dot/commands/)) |
| [Stow packages](/stow/) | One-line blurbs for everything else that is stowed |

## Server

| Page | Why |
| --- | --- |
| [Overview](/server/overview/) | What this build keeps, drops, and still has open |
| [Herdr](/server/herdr/) | Shared agent session that remote clients attach to |

## Agents

| Page | Why |
| --- | --- |
| [Overview](/agents/overview/) | How OpenCode, skills, and companions fit together |
| [Skills](/agents/skills/) | Shared catalogue and repo-local skills |
| [OpenCode](/agents/opencode/overview/) | Primary coding-agent harness |
| [Pi](/agents/pi/) | Lightweight companion agent |

## Machine-readable docs

Build-time [llms.txt](https://llmstxt.org) bundles and a read-only docs MCP, generated from the same source as the site.

| URL | Use |
| --- | --- |
| https://ubuntu-server.dotfiles.timmo.dev/llms.txt | Compact page index |
| https://ubuntu-server.dotfiles.timmo.dev/llms-full.txt | Full docs bundle |
| https://ubuntu-server.dotfiles.timmo.dev/mcp | Hosted MCP (search, page and navigation) |
| `/{route}.md` | One page as Markdown |

Ask AI on the site is off. For live repo state, use [context](https://context.timmo.dev) rather than these static bundles.