sencho/docs/features/editor.mdx

---
title: Editor
description: The per-stack cockpit. Run, restart, update, and update compose files; stream logs; exec into a container.
---

Selecting a stack in the sidebar opens the editor cockpit, a two-column workspace for everything you do to a single stack. The left column is the **Command Center** with the stack's identity, action bar, container list, and log stream. The right column starts on the **Anatomy panel**, a read-only summary of the compose file; clicking **Edit compose** swaps it for an editable Monaco workspace with `compose.yaml`, `.env`, and **Files** tabs. Creating an empty stack lands you there automatically.

<Frame>
  <img src="/images/editor/editor-overview.png" alt="Editor cockpit showing the Command Center and live logs on the left and the Anatomy panel on the right" />
</Frame>

## Command Center

The top card on the left holds the stack's identity and primary controls.

<Frame>
  <img src="/images/editor/command-center.png" alt="Command Center card with breadcrumb, stack title, running status pill, action bar, and the plex container row with live stats" />
</Frame>

| Element | What it shows |
|---------|--------------|
| **Breadcrumb** | `<node> › stacks › <stack>` rendered in caps. Confirms which node the stack lives on. |
| **Stack title** | The stack name in display italic. |
| **Status pill** | Aggregate state: `running · healthy`, `running · starting`, `running · unhealthy`, plain `running` (no healthcheck defined), or `exited` (any non-running state, including stopped, created, and paused). The dot pulses while the stack is running. |

### Stack action bar

The action bar runs every state transition for the whole stack. The primary buttons (**Start**, **Restart**, **Stop**, **Take down** when running, **Update**) require the `stack:deploy` permission; the **Delete** entry in the kebab dropdown requires the `stack:delete` permission. The bar still appears when only **Delete** is authorised so the operator has a way to remove the stack.

<Note>
  If a stack is the Sencho instance you are currently signed into, its deploy/delete actions are protected: clicking any of them opens a **Sencho instance protected** dialog instead of running the action. Update Sencho from **Fleet → Node Update**, or move Sencho's own compose project outside `COMPOSE_DIR` to manage it as a normal stack.
</Note>

| Button | Behavior |
|--------|----------|
| **Start** / **Restart** | A single button that becomes **Restart** when at least one container is running and **Start** otherwise. |
| **Stop** | Stops every container in the stack. Hidden when nothing is running. |
| **Take down** | Shown when at least one container is running. Opens a confirmation dialog, then runs `docker compose down`. Removes containers and compose-created networks while keeping the stack directory. Optional volume removal is offered when the active node supports it. On stopped stacks, use the sidebar context menu or `⌘↓` / `Ctrl+↓`. |
| **Update** | Pulls fresh images and reapplies the compose file. |
| **More actions** (`⋮`) | Opens a dropdown with secondary actions. |

The kebab dropdown carries:

- **Rollback `<timestamp>`** restores the previous deployment using the stored snapshot. Visible only when a backup exists.
- **Scan config** runs Trivy against the compose configuration and surfaces misconfigurations inline. Visible only when Trivy is reachable. Admin role required.
- **Delete** stops the stack and removes its compose directory. Requires the `stack:delete` permission.

## Containers list

Below the action bar, the **CONTAINERS** section lists every container the stack defines. Each row carries a status badge, identity, port mapping, action buttons, and live stats.

<Frame>
  <img src="/images/editor/containers-list.png" alt="Container row showing the green check status badge, container name, uptime, port mapping with an inline open link, action buttons, and CPU MEM and NET I/O stats with sparklines" />
</Frame>

| Element | Detail |
|---------|--------|
| **Status badge** | `✓` (green, healthy or running), `✗` (red, exited or unhealthy), `…` (yellow, starting). |
| **Name** | The Docker container name; falls back to the first 12 characters of the container ID. |
| **Uptime / state** | `up 2h 15m` for running containers, the raw state for everything else. |
| **Healthcheck label** | `healthy`, `unhealthy`, or `starting`, only when a healthcheck is defined. |
| **Port mapping** | The first detected web-UI port, formatted `host → container/proto`. The mapping itself is a link 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. |
| **Action buttons** | **Image source links**, **View logs**, **Open bash shell** (admin only), **Service actions**. Per-container image references and registry links live here, not in the header. |
| **Live stats** | CPU, memory, and net I/O with rolling sparklines. Only rendered while the container is running. Stats refresh on the same 1500 ms cadence as the dashboard. |

### Service actions

When the container has a compose service name attached, an extra `⋮` button appears at the right of the row. It opens **Restart service**, **Stop service**, or **Start service** depending on the current state. Service actions affect a single service; for full-stack operations use the action bar above.

### Multi-container stacks

Stacks with more than one container gain a summary strip above the container list: a total count plus `up`, `paused`, and `unhealthy` counts (only the non-zero ones show). Two view controls sit beside it:

- **Compact / Detailed** toggles whether the CPU/Mem/Net sparkline grid renders under every container row. Detailed is the default for a single-container stack; multi-container stacks default to Compact.
- **Expand containers** collapses the Logs pane so the container list fills the whole left column. Expanding containers and expanding logs (below) are mutually exclusive; opening one closes the other.

## Anatomy panel

The right column shows the **Anatomy panel** by default: a read-only summary of the compose file alongside a scrollable tab row for other stack views.

<Frame>
  <img src="/images/editor/anatomy-tabs.png" alt="Anatomy panel header strip showing the Anatomy, Activity, Doctor, Drift, Dossier, Environment, Networking, and Storage tab row with Files and Edit compose shortcuts on the right" />
</Frame>

The tab row always shows four tabs: **Anatomy**, **Activity**, **Drift**, and **Dossier**. When Compose Doctor is available on the node, **Doctor** sits between Activity and Drift. Four more capability-gated tabs appear when the active node advertises them.

| Tab | Always present? | What it shows |
|-----|----------------|--------------|
| **Anatomy** | Yes | Read-only compose file summary. |
| **Activity** | Yes | Operational event timeline for this stack. See [Stack Activity](/features/stack-activity). |
| **Doctor** | When `compose-doctor` capability is present | Preflight check results grouped by severity. The tab gains a red dot for blocker findings and an amber dot for high-risk findings. See [Compose Doctor](/features/compose-doctor). |
| **Drift** | Yes | Live comparison of the declared compose against the running containers. See [Stack Drift](/features/stack-drift). |
| **Dossier** | Yes | Exportable Markdown of the anatomy combined with operator notes. See [Stack Dossier](/features/stack-dossier). |
| **Environment** | When `env-inventory` capability is present | Variable inventory across all env files, with status for each variable. See [Environment Guardrails](/features/environment-guardrails). |
| **Compose Labels** | When `container-label-inventory` capability is present | Declared Compose labels vs runtime container labels per service. See [Docker Label Audit](/features/docker-label-audit). |
| **Networking** | When `compose-networking` capability is present | Port exposure summary per service with intent classification. See [Compose Networking](/features/compose-networking). |
| **Storage** | When `compose-storage` capability is present | Mount inventory with portability assessment and snapshot coverage. See [Compose Storage](/features/compose-storage). |

The **Files** shortcut and the **Edit compose** button sit at the right end of the strip and stay available regardless of which tab is active.

The Anatomy tab lists:

- **services** as chips
- **ports** in `host → container/proto` rows, grouped by service when the stack defines more than one
- **volumes** in `host → container` rows
- **restart** policy
- **env_file** paths and a count of variables defined in each
- **network** and its driver
- **source** with `git · <host>/<repo>#<branch>` when the stack is linked to a Git repository, or `local` when it is not. Clicking the row opens the Git source dialog. A pulsing brand-color dot means an upstream change is queued.

When an image update is available, or the stack declares services with a local `build:` section, an inline banner appears at the top of the panel. Registry updates follow version-bump severity: `safe to apply` (patch), `review recommended` (minor), `breaking changes possible` (major), or `review required` when the bump cannot be classified. Build-only stacks show **Rebuild available** with a **Rebuild & Update** button. The banner runs the same operation as the action bar's **Update**; it is hidden for roles that lack the `stack:edit` permission and when the bump is flagged as blocked.

If the most recent post-deploy vulnerability scan for this stack failed, partially failed, or was skipped, a dismissible amber banner appears below the update banner (`Last post-deploy scan failed.`, `...partially failed.`, or `Post-deploy scan did not run.`). See [Vulnerability Scanning](/features/vulnerability-scanning) for what triggers a post-deploy scan.

<Frame>
  <img src="/images/editor/scan-status-banner.png" alt="Anatomy panel showing a post-deploy scan failed banner below the compose facts" />
</Frame>

## Editor mode

Clicking **Edit compose** in the Anatomy strip opens an editable Monaco workspace. Creating a new empty stack does the same automatically.

<Frame>
  <img src="/images/editor/editor-edit-mode.png" alt="Editor in edit mode with the compose.yaml tab selected, the Git Source button, the Save and Deploy split button, and the close button visible" />
</Frame>

The editor card has three tabs:

| Tab | Purpose |
|-----|---------|
| `compose.yaml` | YAML editor with syntax highlighting. Always available. |
| `.env` | Environment file editor with syntax highlighting. Disabled when the stack has no env file. |
| **Files** | Browseable directory tree for the stack folder. See the dedicated [Stack File Explorer](/features/stack-file-explorer) page for permissions, upload caps, and protected-file behavior. A full-screen toggle appears next to **Close editor** while this tab is active, collapsing the left column so the file tree and editor use the full width. |

Above the editor area, the toolbar carries:

- **Git Source** opens the Git source dialog. A pulsing brand-color dot appears next to it when an upstream change is waiting to be applied.
- **Save & Deploy** split button (shown as soon as the compose editor opens for operators with `stack:edit`).
- **Close editor** (`X`) discards any unsaved compose and env edits and returns the right column to the Anatomy panel.

When you switch to the `.env` tab and the stack defines more than one env file, a dropdown appears next to the tab strip so you can pick which file to edit. The dropdown locks while you have unsaved edits so switching files cannot drop them. Sencho discovers env files from the `env_file:` entries in `compose.yaml`; if none are declared, it falls back to a `.env` in the stack directory.

The `.env` editor renders a teal banner above the textarea reminding you that variables defined there are available for substitution in `compose.yaml` (`${VAR}`), and that passing them into containers requires an `env_file:` entry on the service.

### Save options

As soon as the compose editor opens, the toolbar shows a split button. The primary action is **Save & Deploy**; the dropdown chevron reveals two more.

| Action | Effect |
|--------|--------|
| **Save & Deploy** | Writes the file to disk, then runs `docker compose up -d` to apply changes. |
| **Save Only** | Writes the file to disk without restarting any containers. Changes take effect on the next deploy. |
| **Discard Changes** | Reverts the active file (compose or env) to the last saved version. Unsaved edits in that file are lost. |

The same controls apply to the `compose.yaml` and `.env` editors.

## Diff preview before save

When **Diff preview before save** is enabled in **Settings → Infrastructure → Stacks**, clicking **Save & Deploy** or **Save Only** opens a side-by-side diff modal before anything is written to disk. The left pane is the on-disk content; the right pane is your unsaved edits with additions highlighted in green. The footer reads `ON DISK → UNSAVED` so the panes are unambiguous.

<Frame>
  <img src="/images/compose-diff-preview/diff-modal.png" alt="Diff preview modal showing side-by-side YAML diff with the unsaved version on the right and an ON DISK to UNSAVED legend in the footer" />
</Frame>

Review the diff, then:

- Click the primary button (**Save & deploy** when triggered from **Save & Deploy**, or **Save** when triggered from **Save Only**) to confirm and write the changes.
- Click **Cancel** to return to the editor without saving.

If there are no unsaved changes the modal is skipped and the save proceeds directly. The toggle is off by default and stored per browser, so each device remembers its own setting.

## On a phone

On a narrow screen the stack opens as a full-screen detail with **Health**, **Logs**, and **Compose** segments instead of the two-column cockpit. The **Compose** segment shows the read-only Anatomy summary; tap **Edit compose** to open a full-screen editor for small, safe changes.

<Frame>
  <img src="/images/editor/editor-mobile.png" alt="Mobile compose editor with a Cancel button, the compose.yaml label, a monospace text field showing the compose file, a small-edits note, and Save and Save and Deploy buttons" />
</Frame>

The mobile editor is a lightweight monospace text field rather than Monaco. Tap **compose** or **.env** at the top to choose the file. The **.env** toggle appears only when the stack has an env file, and the file picker is locked while you have unsaved edits so switching files cannot drop them. The footer carries the same **Save** and **Save & Deploy** actions, and every protection is shared with desktop: the diff preview, save-conflict handling, and the unsaved-changes prompt all behave the same way. **Cancel** leaves the editor and asks before discarding unsaved edits.

A note at the bottom of the editor is a reminder that mobile editing is meant for small corrections such as bumping an image tag or fixing a value. For large compose rewrites, open the stack on a desktop. Editing requires the `stack:edit` permission.

## Logs

Below the Command Center the left column reserves the rest of its height for the **Logs** stream. Two modes are available, toggled by the buttons at the top right of the section.

| Mode | What it shows |
|------|--------------|
| **Structured** | Parses each line for an ISO 8601 timestamp and severity (info, warn, err) and renders rows with filter chips (`all`, `info`, `warn`, `err`) and a counter on the active level. Strips ANSI control codes and auto-follows new lines while you stay at the bottom; scrolling up reveals a **resume follow** button. The buffer is capped at 10,000 lines and the **Download logs** button writes the current buffer to a `.txt` file. |
| **Raw terminal** | A full xterm.js terminal that streams the combined container output verbatim with ANSI color preserved. Press `Ctrl+F` to open the inline find bar. The scrollback is 10,000 lines and a download button is available in the toolbar. |

Both modes connect to the same WebSocket and switch instantly without losing the stream. In Structured mode, an **Expand logs** button next to **Download logs** collapses the Command Center card so the log pane fills the left column; click again (now **Collapse logs**) to bring the Command Center back. This control is mutually exclusive with the container-list **Expand containers** toggle above.

## Log viewer

The **View logs** button on a container row opens a dedicated modal that streams output from a single container in real time using Server-Sent Events. Logs auto-scroll to the bottom as new lines arrive. Close the modal to stop the stream.

## Container exec (bash session)

The **Open bash shell** icon button opens an interactive shell inside a single running container, equivalent to `docker exec -it <id> bash`. The modal uses xterm.js with color, tab completion, and resize handling.

<Frame>
  <img src="/images/editor/container-exec-modal.png" alt="Bash session modal connected to the plex container running cat slash etc slash os release with a Connected status pill" />
</Frame>

### Access requirements

- **Admin role required.** The button is rendered only for admin users.
- **Container must be running.** The button is disabled for stopped containers, and the backend rejects exec attempts against non-running containers.
- **API token scope.** API tokens with the `read-only` or `deploy-only` scope cannot open exec sessions. Only `full-admin` tokens are accepted.

### Shell selection

Sencho tries `/bin/bash` first and transparently falls back to `/bin/sh` if bash is missing. No user action is needed.

<Warning>
  Minimal base images that ship no shell at all (for example `scratch` or fully `distroless`) will not work with container exec.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The compose editor is read-only and I can't type">
    Click **Edit compose** in the Anatomy panel header to open an editable workspace. If that control is missing, your role lacks the `stack:edit` permission; ask an admin to grant it.
  </Accordion>
  <Accordion title="Save & Deploy is disabled">
    A deploy is already running for this stack. Watch the action bar for the spinning state to clear, then save again.
  </Accordion>
  <Accordion title="The .env tab is greyed out">
    The stack has no env file to edit. Add an `env_file:` entry to a service in `compose.yaml` and save, or create a `.env` file in the stack directory through the **Files** tab.
  </Accordion>
  <Accordion title="I can't edit compose from my phone">
    Open the **Compose** segment in the stack detail and tap **Edit compose**. If that affordance is missing, your role lacks the `stack:edit` permission; ask an admin to grant it. The phone editor is intended for small corrections; for large compose rewrites, open the stack on a desktop.
  </Accordion>
  <Accordion title='"Container is not running" error when opening a bash session'>
    The container stopped between clicking the button and the exec starting. Start the container from the action bar (or the row's **Start service** option) and try again.
  </Accordion>
  <Accordion title='"Failed to start shell" error when opening a bash session'>
    The container image has no shell binary at `/bin/bash` or `/bin/sh`. Use an image that includes a shell, or install one in your Dockerfile.
  </Accordion>
  <Accordion title='Bash session connects but immediately shows "Session ended"'>
    The shell process inside the container exited as soon as it started. Check the container logs (the **View logs** button on the same row) for errors; the container's entrypoint may be overriding the shell, or the container itself may be in a crash loop.
  </Accordion>
  <Accordion title="Bash session is unresponsive">
    The WebSocket dropped silently. Close the modal and reopen it to start a fresh session; the bash modal does not reconnect automatically.
  </Accordion>
  <Accordion title='"Failed to save file" toast appears when I click Save & Deploy'>
    The PUT to write the compose file failed (most often a permission or disk-space issue on the node). Save & Deploy stops at the save step in this case, so no deploy is attempted and your editor still holds the unsaved version. Resolve the underlying error on the node, then retry.
  </Accordion>
  <Accordion title="Switching nodes prompts me to discard unsaved changes">
    The editor blocks a silent loss of in-progress edits. Click **Cancel** to return to the original node with your edits intact; click **Discard** to abandon them and proceed to the other node.
  </Accordion>
  <Accordion title='"Sencho instance protected" dialog when I try to stop, update, or delete a stack'>
    That stack is running the Sencho instance you are signed into, and its deploy/delete actions are blocked to prevent locking yourself out. Update Sencho from **Fleet → Node Update** instead. To manage the stack normally, move its compose project to a directory outside `COMPOSE_DIR`.
  </Accordion>
  <Accordion title='"Stats unavailable" chip on the container list'>
    The stats WebSocket failed to open, or closed unexpectedly. This usually means the Docker daemon on the node is unreachable. Container status, action buttons, and logs continue to work; only live CPU / memory / network rates pause.
  </Accordion>
</AccordionGroup>