Terminal Sessions

Open a terminal #

The Terminal bar sits at the bottom of the Console. Open it, then use + to choose a server or project.

• Ctrl + ` shows or hides the Terminal bar.
• Ctrl + Shift + ` opens the server and project picker.

Opening a terminal asks you to confirm your identity with your password or passkey. A session is a real shell on the selected server and can open a root shell.

Choose where the shell starts #

Server session #

Choose a server when the work is not tied to one project. The shell starts in the depfloy user’s home directory. It is useful for checking disk space, inspecting a service, or moving between project directories.

Project session #

Choose a project when the work belongs to one deployed application. The shell starts in that project’s live release directory: current for a zero-downtime project, or the configured project directory otherwise. This is the same working-directory rule as the project’s Commands flow.

If the directory is unavailable, the shell still opens in the home directory and explains why.

Run interactive commands #

Use a terminal when a command needs an answer after it starts, or when you need to inspect the shell before deciding what to run next.

php artisan migrate

The shell stays open after a command finishes. Select Enable sudo to open a root shell within the session; type exit to return to the original shell. Closing the terminal tab, ending the session from the session list, or exiting the outer shell ends the session.

Terminal sessions and Commands #

The project’s Commands tab and Terminal sessions are separate execution paths.

Commands that ask for input are rejected by the Commands queue. Use Open in terminal on a command row to put its text into a project terminal instead. It is not run automatically: review it and press Enter when you are ready.

Keep a session open #

A terminal stays available while you move around the Console or refresh the page. When the browser connection drops, it has a 60-second reconnect window before its shell closes.

• A session closes after 15 minutes without input; it warns one minute beforehand.
• A session lasts at most 4 hours.
• An organization can have at most 10 open sessions.

Exiting the outer shell also closes its session.

Work in a shared session #

Open sessions on servers you can access appear in the Terminal bar’s session list. Join one to watch its output. There is one keyboard at a time:

• the driver can type and resize the terminal;
• watchers see the same output but cannot type;
• a watcher can request control and the driver can grant it;
• the person who opened the session can take control back;
• after five minutes without driver input, a watcher can request control.

Joining a session never grants access to a server you could not otherwise reach.

Permissions #

Owner, Admin and Developer can open, join and end terminal sessions on servers within their access scope. Manager and Viewer do not receive terminal access through their organization role. Server and project scopes still apply: a member restricted to selected resources sees terminals only on those resources.

These rules cover the terminal in the browser. A terminal used by an MCP assistant has one more condition, described in Which assistants can use a terminal.

Use a terminal from MCP #

An MCP assistant can handle an interactive command with these tools:

• open_terminal_session
• elevate_terminal_session
• read_terminal_output
• send_terminal_input
• close_terminal_session

Opening a terminal through MCP always requires approval in Depfloy. That approval covers the session and every command typed in it; Depfloy does not ask again before each keystroke. The assistant should say what it intends to do, read the output before answering a prompt, and close the session when it is done.

read_terminal_output can say that the shell appears to be waiting for input. This is a hint, not proof that an answer is required; inspect the output before typing. MCP-opened sessions are marked as agent sessions in the Console and can be ended by a member who has terminal access to that server.

Root shell in an assistant’s session #

A session opened through MCP starts as the depfloy user. When the work needs root, such as installing a package or editing a file under /etc, the assistant calls elevate_terminal_session.

• Every elevate_terminal_session call waits for a person to approve it under Configuration → MCP → Approvals. This is a second approval, separate from the one that opened the session, and a connection’s approval settings cannot turn it off.
• After you approve it, everything the assistant sends to that session runs as root without another approval.
• A session can be switched to root once. Only the participant holding the keyboard can switch it, and only while the session is open.
• The Activity log records Root shell opened in a terminal session together with the approval that allowed it.

Which assistants can use a terminal #

By default, only the organization Owner’s assistants can open, type into or elevate a terminal session. The Owner can allow Admin and Developer assistants under Configuration → MCP → Connections → Terminal access for assistants. Only the Owner can change this setting; other members see it read-only.

An assistant needs both conditions: its user’s role must include terminal access (Owner, Admin or Developer), and for Admin or Developer the Owner must have allowed that role. Manager and Viewer assistants cannot use terminals because those roles have no terminal access.

When the Owner turns a role off, Depfloy refuses the next input or root request from that role’s assistants, including in sessions that are already open. Close those sessions from Configuration → Terminal sessions if they should end immediately. The terminal in the browser is not affected by this setting.

Review and end active sessions #

Owner and Admin can open Configuration → Terminal sessions to review the organization’s open shells. The page shows where each one runs, who opened it, who has the keyboard, how long it has been open and idle, whether it came from MCP, and whether a root shell was opened in it.

Use End session to close one shell. End all sessions closes every open terminal session. Ending a session also stops anything still running in that shell.

Audit records and retention #

Depfloy records who opened a session, where it ran, and when and why it ended. For commands the terminal shell integration can identify, the audit record includes the command, exit code, duration, and whether it matched a risky-command pattern. A warning does not block the command.

Terminal session records are kept for 90 days. A redacted output excerpt retained for a flagged command is kept for 30 days. Starting another shell without its usual startup configuration can change which commands the shell integration can identify.

Large output #

The terminal protects the browser when a command prints output faster than it can display it. It skips some displayed bytes and says how much was skipped; the command and session continue running, and command audit processing is separate from the display limit.

For continuous output, prefer a bounded command such as:

tail -n 200 storage/logs/laravel.log

Related documentation #

• Commands
• MCP
• Members
• Activity