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

# Terminal & tmux

> How tmux terminal sessions work inside sandboxes, including persistence, named sessions, and key bindings.

## How It Works

Every sandbox runs [tmux](https://github.com/tmux/tmux) as an invisible session manager. Terminal sessions persist across disconnects — running processes, scroll history, and working directory survive browser refreshes, SSH reconnects, and IDE restarts.

Three named sessions are created automatically:

| Session  | Created By              | Attaches When                                           |
| :------- | :---------------------- | :------------------------------------------------------ |
| `vscode` | code-server settings    | Opening a terminal in the browser IDE                   |
| `term`   | ttyd (browser terminal) | Opening `/_term/` in the browser                        |
| `ssh`    | `.bashrc` auto-attach   | Connecting via SSH (VS Code Remote, Cursor, direct SSH) |

Each session is independent. Work in the browser IDE terminal does not appear in the SSH session, and vice versa.

## Session Persistence

tmux sessions persist as long as the container is running.

| Event                           | Sessions Preserved |
| :------------------------------ | :----------------- |
| Browser tab closed and reopened | Yes                |
| SSH disconnect and reconnect    | Yes                |
| IDE restart                     | Yes                |
| Workload container restart      | No                 |
| Suspend and resume              | No                 |

<Note>
  Files, git repos, and installed tools persist across suspend/resume because `/root` is backed by a [volumeset](/reference/volumeset). Only tmux sessions (running processes, shell history in memory) are lost.
</Note>

## Working with tmux

The sandbox tmux configuration hides the status bar and unbinds the prefix key, so it stays invisible. You can still use tmux commands directly:

```bash theme={null} theme={null}
# List all sessions
tmux ls

# Attach to a specific session
tmux attach -t vscode

# Create a new named session
tmux new-session -s my-session

# Kill a session
tmux kill-session -t my-session
```

<Tip>
  To enable standard tmux key bindings, add a prefix to `/root/.tmux.conf`:

  ```bash theme={null} theme={null}
  echo "set -g prefix C-a" >> /root/.tmux.conf
  tmux source-file /root/.tmux.conf
  ```

  This persists across container restarts.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Terminal shows old output after reconnect">
    This is expected. tmux preserves the scrollback buffer. Scroll down or press Enter to get to the current prompt.
  </Accordion>

  <Accordion title="Process still running after closing browser tab">
    tmux keeps processes alive when you disconnect. To stop a process, reattach and terminate it, or kill the session: `tmux kill-session -t term`.
  </Accordion>

  <Accordion title="Clipboard not working in browser IDE">
    Check browser permissions for the sandbox URL. The tmux config enables OSC 52 clipboard support.
  </Accordion>

  <Accordion title="Escape key has a delay in vim/neovim">
    The sandbox tmux config sets `escape-time` to 0. Verify: `tmux show-option -g escape-time`. Reset if needed: `tmux set -g escape-time 0`.
  </Accordion>
</AccordionGroup>