sencho/docs/getting-started/quickstart.mdx

---
title: Quickstart
description: Get Sencho running in under five minutes.
---

This walks you from a clean Docker host to a working Sencho console. Five minutes if your Compose directory is already in the right place, ten if you need to lay it out first.

<Note>
  Sencho is used in production for day-to-day Docker Compose and fleet management. As a pre-1.0 project it still evolves quickly, so review the [known limitations](https://github.com/studio-saelix/sencho/blob/main/KNOWN_LIMITATIONS.md) and validate against your own setup before deploying it on critical infrastructure.
</Note>

## Prerequisites

- Docker and Docker Compose installed on the host.
- A directory where your Compose projects live (for example `/opt/compose`). Each subdirectory inside becomes one stack in Sencho.

<Warning>
  Sencho needs the Docker socket to manage containers. Mounting `/var/run/docker.sock` gives Sencho the same level of Docker control as an operator running Docker commands on the host. For exposed or shared environments, put Sencho behind a TLS-terminating reverse proxy and restrict who can sign in. See [Self-hosting](/operations/self-hosting) for the operational guidance.
</Warning>

## Run with Docker Compose

Drop this into a `docker-compose.yml` next to your Compose tree, or anywhere convenient, and bring it up:

```yaml
services:
  sencho:
    image: saelix/sencho:latest
    container_name: sencho
    restart: unless-stopped
    ports:
      - "1852:1852"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /opt/compose:/opt/compose          # 1:1 path rule, see below
      - sencho_data:/app/data
    environment:
      - COMPOSE_DIR=/opt/compose

volumes:
  sencho_data:
```

```bash
docker compose up -d
```

<Accordion title="Prefer docker run?">

```bash
docker run -d \
  --name sencho \
  --restart unless-stopped \
  -p 1852:1852 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /opt/compose:/opt/compose \
  -v sencho_data:/app/data \
  -e COMPOSE_DIR=/opt/compose \
  saelix/sencho:latest
```

</Accordion>

<Tip>
  Sencho is mirrored on GitHub Container Registry at `ghcr.io/studio-saelix/sencho:latest` with the same tags and digests as Docker Hub. Pull from whichever registry your environment prefers.
</Tip>

<Note>
  `JWT_SECRET` is generated on first boot and persisted to the database. You do not need to provide one.
</Note>

## The 1:1 path rule

The Compose directory must be mounted at the **same path** inside and outside the container. The example above mounts `/opt/compose` to `/opt/compose`, which is correct. If your stacks live somewhere else, adjust both sides of the mount to match.

<Warning>
  This is the most common source of deployment problems. If the host and container paths differ, every relative volume in your Compose files will resolve to the wrong location once Sencho asks Docker to bring a stack up. See the [Configuration guide](/getting-started/configuration#compose-directory-the-11-path-rule) for the full explanation.
</Warning>

## First boot

Open `http://localhost:1852` in a browser. On a fresh install you land on the **Cold start** card, where Sencho asks you to create the first admin account.

<Frame>
  <img src="/images/quickstart/setup-cold-start.png" alt="Sencho first-boot Cold start card with Username, Password, and Confirm password fields, a password strength indicator, and an Initialize console button" />
</Frame>

Pick a username, choose a password, confirm it, and click **Initialize console**. The username placeholder shows `admin`. The password must be at least eight characters, and the strength indicator labels the password **Weak**, **Fair**, or **Strong** as you type.

Sencho then runs a short **environment preflight**: it confirms the Docker engine and Compose plugin are reachable, the compose directory is writable, Sencho's own container isn't nested inside that same directory, the host and container paths match, the dashboard is behind TLS, and there is disk headroom. Anything that needs attention shows an inline fix, like the disk space warning below. The checks never block you, so click **Enter Sencho** to continue; you can re-run them anytime from **Settings · Recovery**.

<Frame>
  <img src="/images/quickstart/setup-environment.png" alt="Sencho first-boot environment preflight with check rows for Docker engine, Docker Compose, Compose directory, Sencho compose location, path mapping, TLS, and disk space, each showing a pass or warning status with inline remediation text, a Re-run button, and an Enter Sencho button" />
</Frame>

<Note>
  The Cold start card only appears the first time you open Sencho. Once the admin account exists, every subsequent visit goes to the regular sign-in screen.
</Note>

## After signing in

You land on **Home**, the default operational view. The health masthead reports **Healthy**, **Degraded**, or **Critical**, names the active node, shows how many nodes are registered, and lists any signals that need attention, alongside a running-container count, a live CPU/memory readout, and an alert count. The resource gauge strip tracks **CPU**, **Memory**, **Disk**, and **Network** with sparklines and threshold coloring. **Stack health** lists the active node's stacks, sorted by load by default (click a column header to sort by name, uptime, CPU, or memory instead), with each row's state, source (**Local** or **Git**), networks, port, uptime, CPU, memory, and a 10-minute CPU sparkline. When more than one node is registered, switch to **All nodes** for a progressive multi-node inventory.

<Frame>
  <img src="/images/quickstart/dashboard.png" alt="Sencho Home view with the health masthead, resource gauges with sparklines, the Stack health table, an operational row pairing Recent alerts with Fleet heartbeat, and the Configuration summary table." />
</Frame>

Below the stack table, the operational row leads with **Recent alerts**, with **Fleet heartbeat** beside it once remote nodes are registered. An alert row opens the stack, scan history, or Fleet updates sheet it points at, and a heartbeat row opens that node's details in Fleet. **Configuration summary** closes the page with one row per domain; expand a domain to see each setting, the scope it applies to, and a link to where it is managed.

On the local node, baseline top navigation includes **Home**, **Resources**, **Networking**, **Security**, and **App Store**. **Fleet** appears when your role can read nodes. **Logs**, **Update**, **Schedules**, and **Console** appear for admins. **Audit** depends on license and role; hub-only views are hidden when a remote node is active. Desktop presentation (Compact launcher, the default, or Smart bar) is chosen under **Settings → Appearance → Navigation**. The right side of the top bar holds global search, notifications, and the profile menu entries **Settings**, **Billing** (when a paid license is active), **Documentation**, **Open New Issue**, and **Log Out**.

The left sidebar is the stack workspace. Below the Sencho brand, it starts with the node switcher, then **Create Stack**, a bulk-mode toggle, and **Scan stacks folder** for re-indexing compose projects added outside Sencho. Use **Search stacks...** with the **All**, **Up**, **Down**, and **Updates** chips to narrow the list. On a fresh install with an empty stack list, Sencho scans your mounted compose directory automatically and shows what it found, including compose files that still need to be adopted into their own subfolder. Once stacks carry Docker Compose labels, the list groups them under those labels, with pinned stacks always floating to the top and unlabeled stacks collected at the bottom.

Click **Create Stack** in the sidebar and choose **Empty**, **From Git**, or **From Docker Run**. Use **Adopt existing files** when Sencho finds compose files that are loose at the compose directory root or one folder too deep (any `.yml` / `.yaml`, not only `compose.yaml`). Loose root files are also auto-promoted into stack folders on the next Sencho restart; adopt is the guided path especially for nested placements. Open **App Store** for a template-driven deploy flow. Once a stack exists, select it in the sidebar or in **Stack health** to open the stack workspace with container health, logs, files, compose editing, and stack actions.

## Where to next

<CardGroup cols={2}>
  <Card title="Configuration" icon="sliders" href="/getting-started/configuration">
    Environment variables, volume mounts, reverse proxy, and the 1:1 path rule in detail.
  </Card>
  <Card title="Stack management" icon="layer-group" href="/features/stack-management">
    Deploy, edit, restart, update, and roll back stacks from the stack workspace.
  </Card>
  <Card title="Multi-node" icon="server" href="/features/multi-node">
    Add a remote Sencho instance and manage it from the same console.
  </Card>
  <Card title="App Store" icon="grid-2" href="/features/app-store">
    Browse the default LinuxServer.io template catalogue and deploy in one click.
  </Card>
  <Card title="Recovery" icon="life-ring" href="/operations/recovery">
    What to do if Sencho, a deploy, sign-in, Docker, or a node fails, and how to get back to a working state.
  </Card>
</CardGroup>