Repository navigation
Shell Access
The Shell modal opens an interactive terminal session inside a running service container. This is equivalent to running docker compose exec <service> <command> from the command line.
Click the ⋮ more menu on any running stack row, then select Shell.
Before the terminal opens, you configure how to connect:
┌──────────────────────────────────────────┐
│ Shell — myapp [✕] │
├──────────────────────────────────────────┤
│ Service [web ▼] │
│ Command [/bin/sh ] │
│ User [ ] │
├──────────────────────────────────────────┤
│ [Open shell] [Cancel] │
└──────────────────────────────────────────┘
| Field | Description |
|---|---|
| Service | The service you want to connect to. If services are detected from the compose file, a dropdown is shown. Otherwise, type the service name manually. |
| Command | The shell to launch inside the container. Defaults to /bin/sh, which works in almost all images. Change to /bin/bash if you prefer bash and it is installed. Quoted arguments are respected (e.g. sh -c "echo foo bar" keeps echo foo bar together as one argument). Suggests previously used commands via your browser's native autocomplete. |
| User (optional) | Run the shell as this user. Leave empty to use the container's default user. Enter root to run as root. |
Click Open shell to connect. The button is disabled if no service name has been entered.
Once connected, the modal shows a full terminal emulator:
┌──────────────────────────────────────────┐
│ Shell — myapp [✕] │
├──────────────────────────────────────────┤
│ # ls / │
│ bin dev etc home proc ... │
│ # _ │
│ │
├──────────────────────────────────────────┤
│ [Disconnect] │
└──────────────────────────────────────────┘
- The terminal supports full color output, cursor movement, tab completion, and all standard terminal features.
- It follows your Cockpit theme: dark background in dark mode, light background in light mode.
- The terminal is a live bidirectional connection — keystrokes are sent to the container in real time.
Click Disconnect to close the terminal session and return to the configuration step. You can then open a new session with different settings.
Closing the modal with ✕ or Escape also disconnects the session.
If the shell cannot be opened (e.g., the service is not running, the command does not exist in the container, or permissions are denied), a red error alert appears below the configuration form with the error message from Docker.
- Most minimal images only have
/bin/sh. If you get "command not found" with/bin/bash, switch to/bin/sh. - To install a package temporarily, run as
rootusing the User field. - Changes made inside the shell affect only the running container and are lost when the container is recreated.
The shell is opened against all of the stack's compose files (not only the first) and with the profiles its compose file declares, so a service that sits behind a profile can be reached too.
Cockpit Compose
Using the UI
- Stacks Dashboard
- Managing Stacks
- Bulk Actions
- Background Tasks
- Viewing Logs
- Editing Configuration
- Stack Info
- Pulling Images
- Events
- Process Viewer
- Shell Access
- Running Commands
- Prune Resources
- Scaling Services
Stack Management
Runtime Support
Help
Development