> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Terminal workspace overview

> The per-project operations workspace where you open application and database shells, run runbooks and commands, and review session history and recordings.

<Tip>
  **Live.** This area is documented as current, user-reliable behavior.
</Tip>

## Goal

Understand what the terminal workspace does, the shell kinds and modes it offers, and how a session is established and bounded.

## Prerequisites

* A project with a running deployment, or a running managed database

## Workflow

<Steps>
  <Step>
    Open a project and go to its Operations / Terminal workspace.
  </Step>

  <Step>
    Pick a target (a running deployment, a release image, a running preview, or a database).
  </Step>

  <Step>
    Pick a mode: running attaches to the live container, ephemeral starts a fresh container from the release image.
  </Step>

  <Step>
    Start the session; the browser connects over a short-lived ticketed WebSocket to the node agent.
  </Step>
</Steps>

## Shell kinds

* Application shell: a /bin/sh session inside the workload container on the node.
* Database shell: a client session into a managed database (psql for Postgres, mysql for MySQL, redis-cli for Redis), with credentials injected for you.

## Session modes

* Running: attach to the live, already-running deployment container. Best for inspecting real state.
* Ephemeral: launch a throwaway container from the release image (useful when the app image has no running container or you want an isolated environment). Writable volumes are off by default and require the volume-write permission.

## Targets you can open

* The active running deployment (running + ephemeral modes).
* A release image (ephemeral only).
* Running preview deployments (running + ephemeral).
* Managed databases attached to the project (running shell only).

## Session lifecycle and limits

Sessions are authorized with a single-use ticket and run over a WebSocket to the node agent. They are bounded by an idle timeout (default 10 minutes) and a hard maximum duration (default 1 hour), and they support a reconnect grace window after a dropped connection. All of these are configurable in the terminal policy.

## Why a shell can fail to open

* No running deployment: running mode needs a deployment in the running state; otherwise use ephemeral.
* No shell in the image: distroless/scratch images have no /bin/sh — use a one-off command or an ephemeral session from a shell-capable image.
* Permission or production gating: see Access and permissions, and Production safeguards.

## Expected result

<Check>
  You get an interactive shell scoped to the chosen target, subject to your permissions and the project terminal policy.
</Check>

## Related guides

<CardGroup cols={2}>
  <Card title="Access and permissions" href="/terminal/access-and-permissions">
    How terminal permissions are derived from team role, project ownership, per-user grants, and platform admin, and what each permission unlocks.
  </Card>

  <Card title="Production safeguards and approvals" href="/terminal/production-safeguards">
    How a target’s environment is classified, why production access is gated, and the reason/approval flow members must follow.
  </Card>

  <Card title="Runbooks and one-off commands" href="/terminal/runbooks-and-commands">
    Run versioned platform and project runbooks, and execute ad-hoc one-off commands, within the project terminal policy.
  </Card>
</CardGroup>