Overhaul Terminal UX

[QarthO]

Currently the terminal UX is a bit lacking. Most notable is the connection dropping and killing the terminal session completely. Currently there is a "reconnected" feature added but its very poorly made and it doesnt reset state prooperly, and often gets stuck in a loop. IMO, This is just the wrong approach to handle this.

My idea is that the terminal session be handled 100% serverside, and the browser just replays the terminal visually, and records keystrokes. This way the browser is independent and the page or tab can be reloaded and the terminal session doesn't get killed or lost. This would also allow the user to be able to swap browsers, or even devices and not loose their terminal session. The session could be handled inside of the coolify-realtime container and live in memory.

I spent some time working with codex to give a rough plan. Here's what it came up with:

---

Simplified Terminal Persistence Plan

Summary

Keep terminal sessions in memory inside the realtime service. The browser becomes an attach/detach client only. If the realtime service restarts, live terminal sessions are lost; that is acceptable.

Build on the recent upstream work: keep their WebSocket heartbeat, visibility reconnect handling, 8-hour session cap, terminal utilities, Livewire keepalive, scrollback preservation, and mobile controls. Replace only the parts that still tie PTY lifetime to one browser connection.

Goal

A terminal session should survive:

• Browser reload
• Dropped WebSocket connection
• Navigation away and back
• Attaching from another browser/device for the same user

A terminal session does not need to survive:

• coolify-realtime restart
• Coolify restart
• Server reboot
• Container restart

Core Change

Move terminal ownership from the browser socket to the realtime process.

Today:

browser websocket -> one PTY -> close websocket kills PTY

Target:

user-owned realtime session -> PTY
browser websocket -> attach/detach view

Realtime Session State

Store live sessions in memory only.

Each session contains:

• Session ID
• Laravel user ID
• Current team ID
• Target type: server or container
• Server identifier
• Container name, if any
• PTY process
• Currently attached socket, if any
• Terminal dimensions
• Bounded output buffer
• Created/attached/detached timestamps
• Expiry timer, using the existing 8-hour max

Browser Protocol

Use explicit message types:

• list: return live sessions owned by this user/team
• create: validate and start a new terminal session
• attach: attach this socket to an existing session
• detach: disconnect this browser without killing the PTY
• terminate: explicitly kill the PTY
• input: send keystrokes
• resize: update terminal dimensions
• ping: keepalive

Only terminate, PTY exit, expiry, or realtime restart should end a session.

Laravel Role

Laravel stays responsible for trust decisions.

Laravel should provide:

• Authenticated user ID
• Current team ID
• Permission to use terminal
• Server/container access validation
• Terminal enabled/disabled validation
• Force-disabled server validation
• Running container validation
• Shell availability validation
• SSH command construction

The browser should no longer receive raw SSH commands. The realtime service asks Laravel for the launch command after Laravel validates the requested target.

Browser Role

The browser should only:

• Render terminal output
• Send input and resize events
• Store the current session ID locally for reload recovery
• Ask realtime for resumable sessions when opened from another device
• Detach on reload/navigation instead of killing the process

Preserve Upstream Improvements

Keep the new upstream work unless it directly conflicts:

• WebSocket ping/pong heartbeat
• Fast reconnect after hidden-tab/proxy drops
• 8-hour terminal cap
• Terminal countdown UI
• Mobile terminal controls
• Livewire keepalive while connected
• Debug logging controls
• SSH parsing and host normalization utilities

Change the “replay last command after reconnect” behavior: it should not be the normal resume mechanism anymore. Resume should attach to the existing PTY. Command replay can be removed or kept only as a fallback for startup races before a session is created.

Security Rules

• Sessions are scoped to user ID and team ID.
• A user can only list, attach, or terminate their own live sessions.
• One active browser attachment per session by default.
• A new attach detaches the previous socket.
• Disabling terminal access blocks new sessions and should prevent reattach.
• Terminal output remains in memory only.
• Output buffer is bounded to avoid unbounded memory growth.

Acceptance Criteria

• Reloading the page keeps the same shell process alive.
• cd /tmp, reload, then pwd still returns /tmp.
• A running foreground command survives browser reconnect.
• Opening another device can list and attach to the existing session.
• Attaching from a second browser detaches the first browser.
• Closing a tab does not kill the terminal.
• Explicit terminate kills the PTY.
• Realtime restart drops sessions cleanly.
• Existing heartbeat, mobile controls, and 8-hour cap continue to work.

Test Scenarios

• Authorized user can create, list, attach, detach, and terminate a session.
• Unauthorized user cannot create or attach.
• User cannot attach to another user’s session.
• Disabled terminal access blocks create and attach.
• Force-disabled server blocks create.
• Invalid or stopped container blocks create.
• WebSocket close detaches without killing the PTY.
• Reattach replays bounded output and resumes input.
• Realtime restart returns no old sessions.