sencho/docs/features/stack-management.mdx

---
title: Stack Management
description: Create, deploy, control, and remove Docker Compose stacks.
---

A **stack** in Sencho is a Docker Compose project: a directory inside your `COMPOSE_DIR` that contains at least a `compose.yaml` (or `docker-compose.yml`) file. Sencho discovers every subdirectory as a stack and surfaces them in the left sidebar.

<Frame>
  <img src="/images/stack-management/sidebar-grouped.png" alt="Sencho sidebar showing the stack list grouped by label, with filter chips at the top" />
</Frame>

## Creating a stack

Click **Create Stack** in the left sidebar to open the **New stack** dialog. Pick a source from the tabs at the top:

- **Empty**: start with a minimal `compose.yaml` skeleton. The default service uses `nginx:latest` with the host port binding commented out, so a fresh deploy never collides with an existing service on the host. Uncomment and adjust the `ports:` block when you're ready to expose the container.
- **From Git**: clone a Git repository so its compose file becomes the stack source. Future webhook pulls keep it in sync. See [Git Sources](/features/git-sources) for the full sync flow.
- **From Docker Run**: paste a `docker run` command and let Sencho convert it to compose YAML.

To bring in compose files that are already on disk but not yet stacks, use **Adopt existing files** (from the empty sidebar, Create Stack footer, or after first-boot preflight). See [Adopt existing files](#adopt-existing-files) below.

When you have no stacks yet, the sidebar shows what Sencho found under your compose directory and offers **Adopt existing files** and **New stack** when those actions apply.

<Frame>
  <img src="/images/stack-management/create-stack-dialog.png" alt="New stack dialog on the Empty tab with a stack name field" />
</Frame>

**Naming rules:**
- Lowercase letters, numbers, and hyphens only (e.g. `my-app`, `nextcloud`)
- No spaces or special characters
- Must be unique; duplicates are rejected

Sencho creates a new directory inside `COMPOSE_DIR` with the chosen seed file. You land in the editor for the new stack and can deploy it from there.

### Adopt existing files

If you already have compose files on disk that are not yet stacks, **Adopt existing files** lists them with a dry preview of each file's services, ports, volumes, and env files. Scanning is read only: it never moves, writes, or changes anything. The only change to disk is the **Move into place** action, which you trigger per file and confirm before it runs. Stacks that already sit in their own subfolder with a standard compose filename (`compose.yaml`, `compose.yml`, `docker-compose.yaml`, or `docker-compose.yml`) are not listed here; they appear in the sidebar.

Adopt surfaces any `.yml` or `.yaml` file that is loose at the compose directory root, or one folder too deep (for example `apps/plex/plex.yml`). Compose override filenames such as `compose.override.yml` are skipped. A top-level folder that only has a non-standard name like `plex/plex.yml` is neither a stack nor an adopt candidate; put a standard compose filename in that folder, or nest one level deeper (for example `apps/plex/plex.yml`). Expand a candidate, give the stack a name, and click **Move into place** to relocate it into its own subfolder; confirm the move, and it appears as a stack in the sidebar. If the file was not already named `compose.yaml`, `compose.yml`, `docker-compose.yaml`, or `docker-compose.yml`, Sencho renames it to `compose.yaml` during the move so the stack registers. This only relocates files on disk: it does not adopt or capture running containers, and containers start only when you deploy the stack. Moving a loose root file relocates only that file, so anything it references by a relative path (such as a root `.env`) stays where it is. You can also arrange the file by hand and click **Rescan** instead.

On startup, Sencho also auto-promotes every top-level `*.yml` / `*.yaml` file in `COMPOSE_DIR` into a `<name>/compose.yaml` stack directory. That migration covers loose root files on the next restart, so adopting a root file is optional if you are about to restart. Nested placements (one directory too deep) are not touched by that migration; adopt is the guided path for those.

The top of the panel shows the directory Sencho is scanning and a reminder of the path rule: each stack lives in its own subfolder, and the host mount path must match the path inside the container so relative volume paths resolve. See [Configuration](/getting-started/configuration) for the full explanation.

If a preview shows a relative volume path (for example `./data:/app/data`), Sencho flags it so you can double check your mount before deploying.

### From Git

The **From Git** tab clones a public or private repository and treats its compose files as the stack's source of truth.

<Frame>
  <img src="/images/stack-management/create-stack-git.png" alt="New stack dialog on the From Git tab with repository URL, branch, the ordered compose-file picker, an optional project directory, authentication, and apply behavior fields" />
</Frame>

Fill in:

- **Stack Name**: same naming rules as the Empty tab.
- **Repository URL**: HTTPS only. SSH URLs are not supported.
- **Branch**: defaults to `main`.
- **Compose files**: one or more paths inside the repository, merged in the listed order. Defaults to `compose.yaml`. Browse the repository tree to pick them, or type a path. An optional **Project directory** sets the base for relative paths.
- **Also sync sibling .env file**: when checked, a `.env` next to the primary compose file is pulled along with it.
- **Authentication**: pick **Public (no auth)** or **Personal Access Token** for private repos.
- **Apply behavior**: controls what happens on future webhook pulls:
  - **Review only**: diffs surface in the sidebar; you apply manually.
  - **Auto-write files**: pulls write to disk; you redeploy manually.
  - **Auto-deploy**: pulls write and redeploy automatically.
- **Deploy after create**: deploys the stack immediately after the repo is cloned.

Click **Create from Git**. Sencho clones the repo, writes the compose files into the stack directory, and (when **Deploy after create** is checked) runs `docker compose up -d`.

### Convert from a docker run command

If you have a `docker run` command from a README, a forum post, or your shell history, the **From Docker Run** tab turns it into a ready-to-deploy `compose.yaml` without hand translation.

<Frame>
  <img src="/images/stack-management/convert-tab-empty.png" alt="New stack dialog on the From Docker Run tab with stack name and command paste fields" />
</Frame>

**How to use it:**

1. Enter a **Stack Name**. Same rules as the Empty tab (lowercase, hyphens, unique).
2. Paste your full command into **Paste your docker run command**. The whole command should be on one logical line; line continuations with `\` are fine.
3. Click **Convert**. Sencho parses the command and shows the resulting compose YAML in a read-only preview below.
4. Review the YAML. If it looks right, click **Create Stack**. Sencho creates the stack directory and writes the converted YAML into `compose.yaml`, then opens the editor on the new stack.

<Frame>
  <img src="/images/stack-management/convert-tab-result.png" alt="Converted compose YAML preview shown after a successful conversion" />
</Frame>

**Supported flags:**

The converter handles the flags you reach for most often:

| Flag | Purpose |
|------|---------|
| `-d` / `--detach` | Detached mode (implied by compose) |
| `--name` | Container name |
| `-p` / `--publish` | Port mappings (`host:container`) |
| `-v` / `--volume` | Volumes and bind mounts |
| `-e` / `--env` | Environment variables |
| `--env-file` | Env file reference |
| `--restart` | Restart policy (`no`, `always`, `unless-stopped`, `on-failure`) |
| `--network` | Attach to a named network |
| `--label` | Container labels |
| `--user` | Run as a specific user |
| `--workdir` | Set the working directory |
| `--entrypoint` | Override the entrypoint |
| `--cap-add` / `--cap-drop` | Linux capabilities |
| `--privileged` | Privileged mode |
| `--read-only` | Read-only root filesystem |
| `--tmpfs` | Temporary filesystem mount |

The image tag is taken from the final positional argument (for example `nginx:alpine`). Any trailing command arguments are preserved as the service `command`.

**Troubleshooting conversion:**

<Frame>
  <img src="/images/stack-management/convert-tab-error.png" alt="Error toast in the bottom-right corner reading 'Could not parse command' while the New stack dialog stays open" />
</Frame>

If the converter cannot produce a usable compose file, the request fails and a toast notification appears in the bottom-right corner. Common causes:

- **Not a docker run command.** The input must begin with `docker run` and include an image reference. Free-form text, `docker compose` commands, and shell pipelines are rejected.
- **Unrecognized flag.** The parser supports the flags listed above. Rare flags (such as `--userns`, `--ipc`, custom runtime options) are not recognized. Remove the flag, convert the rest, and add it back by hand in the editor.
- **Quoting issues.** Multi-line commands with embedded quotes can confuse the parser. Paste the command as a single line with escaped quotes, or simplify the command first.
- **Command is too long.** The endpoint accepts commands up to 8192 characters. Longer inputs are rejected; trim anything you do not need and convert in pieces.

When a flag is not supported, paste the partial output into the **Empty** tab as a starting point and fill in the rest by editing `compose.yaml` directly.

## The stack list

All discovered stacks appear in the left sidebar. The list groups stacks by label and by pinned status, so the most relevant entries surface at the top.

### Status indicator

Each row leads with a two-character status indicator that summarizes the stack's runtime state.

| Indicator | Meaning |
|-----------|---------|
| `UP` (green) | All containers running |
| `PARTIAL` (orange) | Some containers running, at least one exited |
| `DN` (red) | All containers stopped or exited |
| (blank) | No containers running, never deployed, or status unknown |

Additional indicators appear to the right of the stack name:

- A pulsing fuchsia dot flags that an image update is available.
- A muted alert icon replaces the dot when the update check ran but failed to reach the registry or errored.
- A branch icon signals that the Git source's upstream branch has moved ahead of the working copy.

### Search and filter chips

The search box above the list filters stacks by name. The chip row below it filters by state and is independent of search.

<Frame>
  <img src="/images/stack-management/filter-chips.png" alt="Sidebar filter chip row showing All, Up, Down, and Updates with count badges" />
</Frame>

- **All**: every stack discovered in `COMPOSE_DIR`.
- **Up**: stacks where every container is running.
- **Down**: stacks with at least one stopped or exited container.
- **Updates**: stacks with a pending image update.

Each chip carries a live count. Click **Hide filters** in the top-right of the row to collapse the chips when you want a denser list. Search and chips combine: filtering by **Updates** and typing a few characters returns the intersection.

### Pinned and label groups

The list is grouped to keep frequently used stacks reachable.

- **PINNED**: sits at the very top when at least one stack is pinned. Pin a stack with **Pin to top** in the kebab menu (`P` shortcut).
- **Label groups**: each label produces its own collapsible section, header rendered uppercase. See [Stack Labels](/features/stack-labels) for color and assignment options.
- **UNLABELED**: bottom group with everything that has no label.

Click any group header to collapse or expand it. The group's stack count appears in the header.

## Stack header

Opening a stack puts identity and state front and center.

<Frame>
  <img src="/images/stack-view/identity-header.png" alt="Stack identity header showing breadcrumb, title, state pill, and action row for the plex stack" />
</Frame>

The header answers two questions at a glance:

- **What is this?** A breadcrumb (`LOCAL · STACKS · NAME`) and the stack name as the title.
- **Is it healthy?** A state pill to the right of the title reports the live state:
  - `running · healthy` (green) when at least one container reports a passing healthcheck.
  - `running · unhealthy` (red) when any container reports a failing healthcheck.
  - `running · starting` (amber) during the Docker healthcheck start period.
  - `running` (green) when no healthcheck is defined.
  - `exited` (red) when no containers are up.

The action row below the title keeps everyday lifecycle controls visible. The **More actions** overflow holds Rollback, Scan config, Mute, and Delete; the next sections cover both surfaces.

If Sencho discovers its own compose project as a stack (because the deployment directory lives inside `COMPOSE_DIR`), that stack is treated as the running Sencho instance: deploy, update, stop, down, and delete are disabled in the UI and refused by the API. Use **Fleet → Node Update** to upgrade Sencho. Compose Doctor flags the condition during preflight.

### Image source links

Each container row includes a links button that turns the image reference into somewhere useful to go. It opens a small menu with:

- **Open on the registry.** Docker Hub images link to their Docker Hub page; GitHub Container Registry (`ghcr.io`) images link to the owner on GitHub. Images from a private or unrecognized registry show the registry host instead of a link, so you never land on a broken guessed URL.
- **Copy image reference.** Grabs the full reference for use elsewhere.
- **Source, homepage, documentation, and revision links** when the image declares them. These come from the image's own [OCI labels](https://github.com/opencontainers/image-spec/blob/main/annotations.md) (`org.opencontainers.image.source`, `.url`, `.documentation`, `.revision`, `.version`) and are read locally from the image, so they need no internet access and appear only when the image ships them. A revision links to its commit when the source is a GitHub repository; the version is shown as plain text.

The same links button appears on update cards in [Auto-Update Policies](/features/auto-update-policies), so you can review what an image ships and where it comes from before approving an update.

## Container health strip

Below the header, each container in the stack gets a single row that answers "is this piece working, and how do I reach it?" When the stack has multiple containers, a summary strip appears above the list showing total, running, paused, and unhealthy counts, along with a **Compact / Detailed** toggle. Compact mode shows status, name, uptime, port, and action buttons; detailed mode (the default) adds CPU, memory, and network I/O sparklines.

<Frame>
  <img src="/images/stack-view/containers.png" alt="Container card for the plex service showing health badge, uptime, port mapping, open link, action icons, and CPU, memory, and network stat tiles" />
</Frame>

Each row includes:

- **Health badge.** A colored glyph reports the Docker healthcheck state: `✓` green for passing, `✗` red for failing, `…` amber while the healthcheck start period is in flight. Containers without a `healthcheck:` block show a neutral `✓`.
- **Container name** in mono.
- **Meta line.** Uptime (`up 12 hours`) and the primary port mapping (`8989 → 8989/tcp`).
- **Open link.** When the container publishes a port, the mapping itself is a link (`8989 → 8989/tcp ↗`) that opens the service in a new tab, with a **Copy URL** button beside it. The address uses the active node's host and switches to `https` for port 443. Recognised multi-port apps open their web path automatically (for example, Plex opens `/web`).
- **Live stat tiles.** Three tiles show CPU, memory, and network I/O with a rolling sparkline. The sparkline uses the cyan data color and refreshes roughly every 1.5 seconds.
- **Action icons.** The image source links button (see above), plus shortcuts to **View logs**, open a bash shell, and (on single-service stacks) the per-container Start / Stop / Restart kebab.

### Multi-service stacks

When a stack declares more than one Compose service, each service gets its own header above its container cards. That header owns **Update service** or **Rebuild service** (when eligible), the update badge when a registry update is confirmed for that service, and **Start / Stop / Restart** for every replica of the service. Child container cards keep logs, shell, ports, and metrics only.

Build-backed services without a registry update show **Rebuild** wording and no update badge. The editor toolbar **Update** action still updates the entire stack.

Single-service stacks keep the existing flat container layout; service headers do not appear.

## Logs viewer

The logs area at the bottom of the stack view has two modes. Toggle between them with the segmented control in the top-right of the panel; your choice is remembered for next time.

<Frame>
  <img src="/images/stack-view/logs-viewer.png" alt="Logs panel in Structured mode for the plex stack with toolbar, level filter pills, and timestamped INFO log rows" />
</Frame>

**Structured** (default) parses every line into a DOM row with three columns: local time, level badge, and message. Level detection is automatic:

- `err` rows get a red left rail and a subtle rose tint.
- `warn` rows get a warm tint.
- `info` rows render plainly.

The toolbar includes:

- **Following indicator.** A green dot reads `following` while auto-scroll is engaged. Scrolling up stops follow; a `resume follow` link re-engages it and jumps to the bottom.
- **Level filter.** `ALL · INFO · WARN · ERR` pills. The `ERR` pill shows the running error count as a badge.
- **Download.** Exports the current buffer as a plain text file.

The structured viewer holds up to 10,000 lines; older entries are dropped from the top as new ones arrive.

**Raw terminal** keeps the original xterm-based viewer for cases where ANSI art, control sequences, or interactive TTY output matter. Lines include the raw ISO timestamp.

## Anatomy panel

The right column of the stack view is a tabbed panel: Anatomy, Activity, Dossier, Drift, Environment, Compose Labels, Networking, Doctor, and Storage. Tabs appear only when the data they need is available, and the row scrolls horizontally (with a chevron button) when there are more tabs than fit.

<Frame>
  <img src="/images/stack-view/anatomy-panel.png" alt="Anatomy panel with the Anatomy tab active, showing services, ports, volumes, restart, env_file, network, and source rows plus the tab row" />
</Frame>

The **Files** and **Edit compose** buttons sit to the right of the tab row.

- **Files**: opens the in-stack file explorer; see [Stack File Explorer](/features/stack-file-explorer).
- **Edit compose**: opens an editable Monaco workspace for compose and env edits.

### Anatomy

Each row maps one compose concept to the value it resolves to right now:

- **Services**: Cyan pills, one per key under `services:`.
- **Ports**: `{host} → {container}/{proto}` per service, host port highlighted.
- **Volumes**: `{host-path} → {container-path}` per mount.
- **Restart**: The effective restart policy.
- **Env file**: Filename plus a count of defined variables. If the compose file references a `${VAR}` that the env file does not define and has no `:-default`, the missing name is called out inline.
- **Network**: Derived network name and driver (default `{stack}_default · bridge`).
- **Source**: `git · {host}/{repo}#{branch}` when Git Source is configured, else `local`. The whole row is clickable and opens the Git Source dialog. A pulsing dot appears when upstream has moved ahead of the working copy.

A footer card under the rows surfaces the first published port as a clickable **EXPOSED** link, so you can jump straight to the running app.

If an image update is available, or the stack declares one or more services with a local `build:` section, an inline banner appears below the rows. Registry updates name each image with a pending update and show its version transition (for example `27.1.4 -> 27.1.5`); the detail line below reads `patch · safe to apply` (green), `minor · review recommended` (amber), or `major · breaking changes possible` (rose), followed by an **apply** button. Build-only stacks show **Rebuild available** instead of a version bump, with a **Rebuild & Update** button. A stack that mixes registry images and local builds still shows a single banner, with the rebuild note folded into the same detail line. Major bumps use the rose styling and are worth reviewing before applying.

Rebuilds can take longer than a registry pull and depend on the local Dockerfile context, network access, and base-image availability. Atomic rollback restores compose and env files only; previously built image layers are not rolled back automatically.

A separate amber **scan** banner appears here if the most recent post-deploy vulnerability scan failed or was skipped for one or more images; deploys are never blocked by a scan failure. See [Vulnerability Scanning](/features/vulnerability-scanning).

### Activity

A timestamped audit trail of every deploy, restart, stop, update, and rollback on this stack, attributed to the user or subsystem that triggered it. See [Stack Activity](/features/stack-activity).

### Dossier

A generated summary of what the stack declares (services, ports, volumes, network, source) combined with a free-text notes section where you can record purpose, owner, access URLs, backup procedure, and recovery steps. Exports to Markdown. See [Stack Dossier](/features/stack-dossier).

### Drift

Compares the running containers against what the compose file declares. Reports services, images, and ports that have diverged from the compose definition since the last deploy. See [Stack Drift](/features/stack-drift).

### Environment

An inventory of every environment variable the stack uses, organized by status:

- **Present**: defined in the env file and referenced by the compose file.
- **Missing**: referenced in the compose file but absent from the env file.
- **Duplicate**: defined more than once across env files or sources.
- **Unpersisted**: injected at runtime (shell export) but not saved to any file.
- **Unused**: defined in the env file but never referenced by any service.

Variables that look like secrets (tokens, passwords, keys) are marked with a lock icon. When the stack references multiple env files, use the file picker in the tab header to switch between them.

### Compose Labels

Reconciles the Docker labels declared in the compose file against the labels present on each running container, per service, with a provenance badge (Compose file, Image, Runtime, or System) on every entry. These are Docker labels read by external automation such as Watchtower or Traefik, distinct from Sencho's own organizational Stack Labels (see [Stack Labels](/features/stack-labels)). See [Docker Label Audit](/features/docker-label-audit) for the full reconciliation model and the fleet-wide equivalent.

### Networking

Shows the stack's defined networks, external network attachments, and the driver for each, along with an exposure-intent classification per service. A Runtime Drift row confirms whether the running network topology matches what the compose file declares. See [Compose Networking](/features/compose-networking).

### Doctor

Runs preflight checks against the compose file and reports findings grouped by severity:

| Severity | Meaning |
|----------|---------|
| **Blocker** | Deploy will fail or behave incorrectly as configured |
| **High risk** | Significant misconfiguration or security concern |
| **Warning** | Best-practice deviation worth reviewing |
| **Info** | Informational observation, no action required |

Each finding includes the affected service, a description, and a remediation suggestion. Click **run preflight** to rerun the checks. When the last run found blocker or high-risk findings, the **Doctor** tab label shows a small red or amber dot until you rerun preflight or dismiss the summary banner. See [Compose Doctor](/features/compose-doctor).

### Storage

Analyzes the stack's volume and bind-mount configuration and reports a portability status:

- **Portable**: all mounts use named volumes or relative bind paths. The stack can be moved to another host without path changes.
- **Partially portable**: some mounts use absolute host paths; others are portable.
- **Node-bound**: one or more mounts pin the stack to a specific host path, socket, or symlink that may not exist on another node.

Each mount row shows its type (bind, named, anonymous, tmpfs, socket), permissions (rw or ro), the host path, the container path, and whether the source path exists on disk. See [Compose Storage](/features/compose-storage).

### Editing compose.yaml

Click **Edit compose** in the panel header to open an editable Monaco workspace. Tabs at the top switch between `compose.yaml`, `.env` (when one exists), and **Files** (the stack directory tree). The save split-button reads **Save & Deploy** by default; its dropdown also offers **Save Only** and **Discard Changes**. Close the editor to return to the anatomy view; closing discards any unsaved compose and env edits. See [Compose Editor](/features/editor) for autocomplete, schema validation, and Git Source workflow.

## Deploying a stack

Select a stack and click **Start** (or **Restart** when it's already running) in the stack header. This runs `docker compose up -d`, pulling images if needed and creating or recreating containers.

For deploy progress, error surfacing, atomic backups, and rollback, see [Atomic Deployments](/features/atomic-deployments).

If a deploy policy is configured, Sencho checks it before the deploy runs. When a policy is violated, a dialog lists the triggered rules and blocks the deploy. Admin users see a **Deploy anyway** button to override the block. See [Deploy Enforcement](/features/deploy-enforcement) for configuring policies.

## Controlling a running stack

The stack header groups actions by frequency of use. The most common action is the filled cyan button on the left, everyday secondaries sit next to it, and destructive or occasional actions are tucked behind the **More actions** overflow.

**When running:**

| Placement | Button | Command | What it does |
|-----------|--------|---------|--------------|
| Primary | **Restart** | `docker compose restart` | Restarts all containers in the stack. |
| Secondary | **Stop** | `docker compose stop` | Stops containers without removing them. State is preserved. |
| Secondary | **Take down** | `docker compose down` | Removes containers and compose-created networks. The stack definition stays on disk so you can deploy again later. Optional volume removal is available in the confirmation dialog. |
| Secondary | **Update** | `docker compose pull` + `up -d` (or build-aware rebuild when services declare `build:`) | Pulls registry images and recreates containers. When one or more services use `build:`, Update rebuilds those images from source (`compose build --pull`), pulls any remaining registry images, then recreates containers. |
| Overflow | **Rollback** | Restores backup | Reverts compose and env files to the pre-deploy snapshot and redeploys. Only shown when a backup exists. |
| Overflow | **Scan config** | Trivy config scan | Scans the compose file for misconfigurations (admin role). |
| Overflow | **Mute** | Creates a mute rule | Quick presets to mute notifications, deploy-success noise, or monitor alerts for this stack, plus a link to manage its mute rules in full. See [Alerts and Notifications](/features/alerts-notifications). |
| Overflow | **Delete** | `down --volumes` + removes files | Stops and removes containers and volumes, then deletes the stack directory. |

**When stopped:**

| Placement | Button | Command | What it does |
|-----------|--------|---------|--------------|
| Primary | **Start** | `docker compose up -d` | Starts the stack. |
| Secondary | **Update** | `docker compose pull` + `up -d` (or build-aware rebuild when services declare `build:`) | Pulls registry images and recreates containers. When one or more services use `build:`, Update rebuilds those images from source (`compose build --pull`), pulls any remaining registry images, then recreates containers. |
| Overflow | **Delete** | Removes files | Deletes the stack directory. |

Use the sidebar context menu or `⌘↓` / `Ctrl+↓` for **Take down** on a stopped stack.

<Warning>
  **Delete** is irreversible. It removes the stack directory, including `compose.yaml`, `.env`, and any bind-mounted files stored there. Back up important files before deleting.

  **Take down** keeps your compose files on disk. It removes running containers and compose-created networks. When you opt in to volume removal, named and anonymous compose volumes are removed as well. Use **Stop** when you want containers to stay in place for a quick resume.
</Warning>

<Note>
  Stack directories often contain root-owned files, either because Docker Compose creates them, or because the stacks were originally set up outside of Sencho with `sudo`. Sencho handles this automatically: if a normal deletion fails due to permissions, it uses Docker to clean up root-owned files. No manual intervention is needed in the standard setup.
</Note>

## Bulk mode

Bulk mode lets you run a single lifecycle action across several stacks at once, instead of opening each stack individually.

<Frame>
  <img src="/images/stack-management/bulk-action-bar.png" alt="Sidebar with bulk mode active, three stacks selected, and the action bar showing Start, Stop, Restart, and Update buttons" />
</Frame>

**Enter bulk mode** with the toggle next to **Create Stack** in the sidebar, or by pressing `B`. Each stack row turns into a checkbox.

**Select stacks** by clicking rows. The action bar above the list shows `{N} selected` and a **Clear selection** link.

**Run an action** with one of the four buttons:

- **Start**: deploys every selected stack that is currently down.
- **Stop**: stops every selected stack that is currently running.
- **Restart**: restarts every selected stack that is currently running.
- **Update**: pulls the latest image tags and redeploys.

Press `B` again or toggle the bulk mode button to leave bulk mode.

## Controlling a single service

Inside the stack detail view, each container card has a **Service actions** kebab on the right side. Use it to act on that service without touching the rest of the stack.

- **Restart service**: stops and starts all containers for that service.
- **Stop service**: stops all containers for that service. Only shown when the service is running.
- **Start service**: starts all containers for that service. Only shown when the service is stopped or exited.

For services running multiple replicas, the action applies to every replica simultaneously. Sibling services are not affected.

<Note>
  The service name in the action must match the `services:` key in your `compose.yaml`. If no containers exist yet for that service, the action will fail with a "service not found" error. Make sure the service is defined in the compose file and has been deployed at least once.
</Note>

## Stack context menu

Click the kebab on a stack row in the sidebar to open its context menu. The menu adapts to the stack's current state; items are grouped by purpose.

<Frame>
  <img src="/images/stack-management/context-menu.png" alt="Sidebar stack context menu showing inspect, organize, lifecycle, and destructive groups with keyboard shortcuts" />
</Frame>

**inspect**

- **Alerts** (`A`): open the alert rule editor for this stack. See [Alerts and Notifications](/features/alerts-notifications).
- **Auto-Heal** (`H`): configure auto-recovery for this stack. See [Auto-Heal Policies](/features/auto-heal-policies).
- **Check updates** (`U`): force an image update check now.
- **Open App** (`↗`): open the stack's web interface in a new tab. Shown only when the stack is running and exposes a web port.
- **Mute** (`›`): quick presets to mute notifications, deploy-success noise, or monitor alerts for this stack, plus a link to manage its mute rules in full. See [Alerts and Notifications](/features/alerts-notifications).

**organize**

- **Labels** (`L ›`): assign or remove labels. See [Stack Labels](/features/stack-labels).
- **Pin to top** (`P`): pins the stack to the **PINNED** group at the top of the list; toggles to **Unpin** once pinned.

**lifecycle**

- **Deploy** (`⌘↵`): shown when stopped, in place of Stop and Restart.
- **Stop** (`⌘.`): shown when running.
- **Restart** (`⌘R`): shown when running.
- **Update** (`⌘↑`): pulls the latest image tags and redeploys.
- **Take down** (`⌘↓`): shown when the stack has been deployed (running, partial, or exited). Opens a confirmation dialog; optional volume removal is offered when the active node supports it. Disabled for the stack running Sencho itself.
- **Schedule task**: admin only. Opens the scheduler pre-filled for this stack; pick **Auto-update Stack** to set up unattended image updates on your own cadence. See [Scheduled Operations](/features/scheduled-operations) and [Auto-Update Policies](/features/auto-update-policies).

**destructive**

- **Delete** (`⌘⌫`): admin only. Disabled for the stack running Sencho itself.

Items are disabled while another operation is in progress on that stack.

## Scanning for stacks

If you place Docker Compose files directly into the stacks directory (for example, via `scp`, a file manager, or the command line), click **Scan stacks folder** to re-index subdirectories that already look like stacks. For compose files that are loose at the root or one folder too deep, use [Adopt existing files](#adopt-existing-files).

<Frame>
  <img src="/images/stack-management/sidebar-actions.png" alt="Sidebar action row with Create Stack button, bulk mode toggle, and scan stacks folder icon button" />
</Frame>

Click the **Scan stacks folder** icon button to the right of **Create Stack**. Sencho scans the configured stacks directory and reports what it finds:

- **New stacks detected**: a success notification lists the newly discovered stack names, and they appear immediately in the sidebar.
- **Stacks removed from disk**: an informational notification lists stacks that are no longer present in the directory.
- **No changes**: a notification confirms no new stacks were found.

<Tip>
  Any subdirectory inside your `COMPOSE_DIR` that contains a `compose.yaml`, `compose.yml`, `docker-compose.yaml`, or `docker-compose.yml` file is recognized as a valid stack.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Service action returns a 'service not found' error">
    The service name used in the action must match the `services:` key in the stack's `compose.yaml`. This error occurs when no running containers match that service name, either because the service was never deployed or because the compose file defines a different name. Verify the service key in your compose file and ensure the stack has been deployed at least once so containers exist for that service.
  </Accordion>
  <Accordion title="A published port link opens but the service does not load">
    The link targets the active node's host and the published host port. It cannot reach a service bound only to `127.0.0.1` on the node, or one published on a port your browser cannot route to. For a remote node, the link uses that node's host; if the service lives at a different address, open it there directly. A port that is not published to a host port has no link.
  </Accordion>
</AccordionGroup>