Skip to content

An open-source, self-hostable PaaS alternative to Vercel, Heroku & Netlify that lets you easily deploy static sites, databases, full-stack applications and 360+ one-click services on your own servers.

fix(terminal): keep sessions alive without hard timeouts

Andras Bacsaib46d8e260146
diff --git a/app/Helpers/SshMultiplexingHelper.php b/app/Helpers/SshMultiplexingHelper.php
index 021ac3608d..d0bd8d3a37 100644
--- a/app/Helpers/SshMultiplexingHelper.php
+++ b/app/Helpers/SshMultiplexingHelper.php
@@ -69,7 +69,7 @@ class SshMultiplexingHelper
return $scpCommand.escapeshellarg($source).' '.self::escapedUserAtHost($server).':'.escapeshellarg($dest);
}
- public static function generateSshCommand(Server $server, string $command, bool $disableMultiplexing = false): string
+ public static function generateSshCommand(Server $server, string $command, bool $disableMultiplexing = false, ?int $commandTimeout = null): string
{
if ($server->settings->force_disabled) {
throw new \RuntimeException('Server is disabled.');
@@ -80,7 +80,8 @@ class SshMultiplexingHelper
self::validateSshKey($server->privateKey);
- $sshCommand = 'timeout '.config('constants.ssh.command_timeout').' ssh ';
+ $commandTimeout = $commandTimeout ?? (int) config('constants.ssh.command_timeout');
+ $sshCommand = $commandTimeout > 0 ? "timeout {$commandTimeout} ssh " : 'ssh ';
if (! $disableMultiplexing && self::isMultiplexingEnabled()) {
$sshCommand .= self::multiplexingOptions($server);
diff --git a/app/Livewire/Project/Shared/Terminal.php b/app/Livewire/Project/Shared/Terminal.php
index bbc2b3e66f..db65cdaadc 100644
--- a/app/Livewire/Project/Shared/Terminal.php
+++ b/app/Livewire/Project/Shared/Terminal.php
@@ -12,6 +12,8 @@ class Terminal extends Component
{
public bool $hasShell = true;
+ public bool $isTerminalConnected = false;
+
private function checkShellAvailability(Server $server, string $container): bool
{
$escapedContainer = escapeshellarg($container);
@@ -65,12 +67,20 @@ class Terminal extends Component
$dockerCommand = "sudo {$dockerCommand}";
}
- $command = SshMultiplexingHelper::generateSshCommand($server, $dockerCommand);
+ $command = SshMultiplexingHelper::generateSshCommand(
+ $server,
+ $dockerCommand,
+ commandTimeout: (int) config('constants.terminal.command_timeout')
+ );
} else {
$shellCommand = 'PATH=$PATH:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin && '.
'if [ -f ~/.profile ]; then . ~/.profile; fi && '.
'if [ -n "$SHELL" ] && [ -x "$SHELL" ]; then exec $SHELL; else sh; fi';
- $command = SshMultiplexingHelper::generateSshCommand($server, $shellCommand);
+ $command = SshMultiplexingHelper::generateSshCommand(
+ $server,
+ $shellCommand,
+ commandTimeout: (int) config('constants.terminal.command_timeout')
+ );
}
// ssh command is sent back to frontend then to websocket
// this is done because the websocket connection is not available here
@@ -84,6 +94,23 @@ class Terminal extends Component
$this->dispatch('send-back-command', $command);
}
+ #[On('terminalConnected')]
+ public function markTerminalConnected(): void
+ {
+ $this->isTerminalConnected = true;
+ }
+
+ #[On('terminalDisconnected')]
+ public function markTerminalDisconnected(): void
+ {
+ $this->isTerminalConnected = false;
+ }
+
+ public function keepTerminalPageAlive(): void
+ {
+ $this->isTerminalConnected = true;
+ }
+
public function render()
{
return view('livewire.project.shared.terminal');
diff --git a/config/constants.php b/config/constants.php
index 89b633650d..fd66a682a0 100644
--- a/config/constants.php
+++ b/config/constants.php
@@ -35,6 +35,7 @@ return [
'protocol' => env('TERMINAL_PROTOCOL'),
'host' => env('TERMINAL_HOST'),
'port' => env('TERMINAL_PORT'),
+ 'command_timeout' => 0,
],
'pusher' => [
diff --git a/docker/coolify-realtime/terminal-server.js b/docker/coolify-realtime/terminal-server.js
index 42ca7c81d8..c76383b9f6 100755
--- a/docker/coolify-realtime/terminal-server.js
+++ b/docker/coolify-realtime/terminal-server.js
@@ -63,8 +63,8 @@ function createHttpError(response) {
}
const userSessions = new Map();
-const terminalDebugEnabled = ['1', 'true', 'yes'].includes(
- String(process.env.TERMINAL_DEBUG || '').toLowerCase()
+const terminalDebugEnabled = ['local', 'development'].includes(
+ String(process.env.APP_ENV || process.env.NODE_ENV || '').toLowerCase()
);
function logTerminal(level, message, context = {}) {
@@ -154,7 +154,6 @@ const verifyClient = async (info, callback) => {
const wss = new WebSocketServer({ server, path: '/terminal/ws', verifyClient: verifyClient });
const HEARTBEAT_INTERVAL_MS = 30000;
-const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
wss.on('connection', async (ws, req) => {
ws.isAlive = true;
@@ -168,7 +167,6 @@ wss.on('connection', async (ws, req) => {
ptyProcess: null,
isActive: false,
authorizedIPs: [],
- lastActivityAt: Date.now(),
authReady: false,
pendingMessages: [],
};
@@ -260,29 +258,6 @@ const heartbeat = setInterval(() => {
} catch (_) {
// ignore — close handler will follow
}
-
- const session = ws.userId ? userSessions.get(ws.userId) : null;
- if (session?.isActive && session.lastActivityAt && (Date.now() - session.lastActivityAt > IDLE_TIMEOUT_MS)) {
- const idleMs = Date.now() - session.lastActivityAt;
- logTerminal('warn', 'Closing terminal session due to idle timeout.', {
- userId: ws.userId,
- idleMs,
- idleTimeoutMs: IDLE_TIMEOUT_MS,
- });
- try {
- ws.send('idle-timeout');
- } catch (_) {
- // ignore — close still attempted below
- }
- killPtyProcess(ws.userId);
- setTimeout(() => {
- try {
- ws.close(1000, 'Idle timeout');
- } catch (_) {
- // ignore — already closed
- }
- }, 100);
- }
});
}, HEARTBEAT_INTERVAL_MS);
@@ -290,11 +265,9 @@ wss.on('close', () => clearInterval(heartbeat));
const messageHandlers = {
message: (session, data) => {
- session.lastActivityAt = Date.now();
session.ptyProcess.write(data);
},
resize: (session, { cols, rows }) => {
- session.lastActivityAt = Date.now();
cols = cols > 0 ? cols : 80;
rows = rows > 0 ? rows : 30;
session.ptyProcess.resize(cols, rows)
@@ -420,7 +393,6 @@ async function handleCommand(ws, command, userId) {
userSession.ptyProcess = ptyProcess;
userSession.isActive = true;
- userSession.lastActivityAt = Date.now();
ws.send('pty-ready');
diff --git a/package-lock.json b/package-lock.json
index bcacecc8b9..9d495c412d 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1261,8 +1261,7 @@
"version": "5.5.0",
"resolved": "https://registry.npmjs.org/@xterm/xterm/-/xterm-5.5.0.tgz",
"integrity": "sha512-hqJHYaQb5OptNunnyAnkHyM8aCjZ1MEIDTQu1iIbbTD/xops91NB5yq1ZK/dC2JDbVWtF23zUtl9JE2NqwT87A==",
- "license": "MIT",
- "peer": true
+ "license": "MIT"
},
"node_modules/clsx": {
"version": "2.1.1",
@@ -1752,7 +1751,6 @@
"integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
"dev": true,
"license": "MIT",
- "peer": true,
"engines": {
"node": ">=12"
},
@@ -1946,8 +1944,7 @@
"version": "4.1.18",
"resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.1.18.tgz",
"integrity": "sha512-4+Z+0yiYyEtUVCScyfHCxOYP06L5Ne+JiHhY2IjR2KWMIWhJOYZKLSGZaP5HkZ8+bY0cxfzwDE5uOmzFXyIwxw==",
- "license": "MIT",
- "peer": true
+ "license": "MIT"
},
"node_modules/tapable": {
"version": "2.3.0",
@@ -1992,7 +1989,6 @@
"integrity": "sha512-Bby3NOsna2jsjfLVOHKes8sGwgl4TT0E6vvpYgnAYDIF/tie7MRaFthmKuHx1NSXjiTueXH3do80FMQgvEktRg==",
"dev": true,
"license": "MIT",
- "peer": true,
"dependencies": {
"esbuild": "^0.27.0",
"fdir": "^6.5.0",
diff --git a/resources/js/terminal.js b/resources/js/terminal.js
index 7a7fc85365..cb3a26b3a6 100644
--- a/resources/js/terminal.js
+++ b/resources/js/terminal.js
@@ -44,7 +44,7 @@ export function initializeTerminalComponent() {
pendingCommand: null,
// Last successfully sent SSH command — replayed after a transient reconnect
// so the PTY respawns automatically. Cleared on intentional terminations
- // (pty-exited, idle-timeout, unprocessable).
+ // (pty-exited, unprocessable).
lastSentCommand: null,
// Resize handling
resizeObserver: null,
@@ -462,15 +462,6 @@ export function initializeTerminalComponent() {
// Notify parent component that terminal disconnected
this.$wire.dispatch('terminalDisconnected');
- } else if (event.data === 'idle-timeout') {
- this.$wire.dispatch('error', 'Terminal closed after 30 minutes of inactivity.');
- this.terminalActive = false;
- if (this.term) {
- this.term.reset();
- }
- this.commandBuffer = '';
- this.lastSentCommand = null;
- this.$wire.dispatch('terminalDisconnected');
} else if (
typeof event.data === 'string' &&
(event.data.startsWith('Unauthorized:') || event.data.startsWith('Invalid SSH command:'))
diff --git a/resources/views/livewire/project/shared/terminal.blade.php b/resources/views/livewire/project/shared/terminal.blade.php
index c46c5f3169..abcb366f52 100644
--- a/resources/views/livewire/project/shared/terminal.blade.php
+++ b/resources/views/livewire/project/shared/terminal.blade.php
@@ -1,4 +1,7 @@
<div id="terminal-container" x-data="terminalData()">
+ @if ($isTerminalConnected)
+ <div class="hidden" aria-hidden="true" wire:poll.keep-alive.30s="keepTerminalPageAlive"></div>
+ @endif
@if (!$hasShell)
<div class="flex pt-4 items-center justify-center w-full py-4 mx-auto">
<div class="p-4 w-full rounded-sm border dark:bg-coolgray-100 dark:border-coolgray-300">
diff --git a/tests/Feature/RealtimeTerminalPackagingTest.php b/tests/Feature/RealtimeTerminalPackagingTest.php
index ba01deca58..c478f79b87 100644
--- a/tests/Feature/RealtimeTerminalPackagingTest.php
+++ b/tests/Feature/RealtimeTerminalPackagingTest.php
@@ -58,22 +58,35 @@ it('uses a fast probe timeout when the tab regains visibility', function () {
->toContain("'Visibility-resume timeout'");
});
-it('closes idle terminal sessions after 30 minutes on the server', function () {
+it('does not hard close terminal sessions after 30 minutes on the server', function () {
$terminalServer = file_get_contents(base_path('docker/coolify-realtime/terminal-server.js'));
expect($terminalServer)
- ->toContain('IDLE_TIMEOUT_MS = 30 * 60 * 1000')
- ->toContain('lastActivityAt')
- ->toContain("ws.send('idle-timeout');")
- ->toContain("ws.close(1000, 'Idle timeout');");
+ ->not->toContain('IDLE_TIMEOUT_MS = 30 * 60 * 1000')
+ ->not->toContain("ws.send('idle-timeout');")
+ ->not->toContain("ws.close(1000, 'Idle timeout');");
});
-it('reacts to idle-timeout sentinel on the client and shows a user-facing error', function () {
+it('does not close the client terminal from an idle-timeout sentinel', function () {
$terminalClient = file_get_contents(base_path('resources/js/terminal.js'));
expect($terminalClient)
- ->toContain("event.data === 'idle-timeout'")
- ->toContain('Terminal closed after 30 minutes of inactivity.');
+ ->not->toContain("event.data === 'idle-timeout'")
+ ->not->toContain('Terminal closed after 30 minutes of inactivity.');
+});
+
+it('keeps Livewire alive in background tabs while a terminal is connected', function () {
+ $terminalComponent = file_get_contents(base_path('app/Livewire/Project/Shared/Terminal.php'));
+ $terminalView = file_get_contents(base_path('resources/views/livewire/project/shared/terminal.blade.php'));
+
+ expect($terminalComponent)
+ ->toContain('public bool $isTerminalConnected = false;')
+ ->toContain("#[On('terminalConnected')]")
+ ->toContain('public function markTerminalConnected(): void')
+ ->toContain('public function keepTerminalPageAlive(): void')
+ ->and($terminalView)
+ ->toContain('@if ($isTerminalConnected)')
+ ->toContain('wire:poll.keep-alive.30s="keepTerminalPageAlive"');
});
it('replays the last command on reconnect so the PTY respawns automatically', function () {
diff --git a/tests/Feature/SshMultiplexingLockTest.php b/tests/Feature/SshMultiplexingLockTest.php
index e97be1f502..b914765f64 100644
--- a/tests/Feature/SshMultiplexingLockTest.php
+++ b/tests/Feature/SshMultiplexingLockTest.php
@@ -73,6 +73,19 @@ it('adds native openssh multiplexing options to ssh commands', function () {
Process::assertNothingRan();
});
+it('can generate terminal ssh commands without a hard command timeout', function () {
+ config(['constants.ssh.mux_enabled' => true]);
+ $server = makeMuxServer();
+ Storage::disk('ssh-keys')->put("ssh_key@{$server->privateKey->uuid}", $server->privateKey->private_key);
+
+ $command = SshMultiplexingHelper::generateSshCommand($server, 'echo ok', commandTimeout: 0);
+
+ expect($command)
+ ->toStartWith('ssh ')
+ ->not->toStartWith('timeout ')
+ ->not->toContain('timeout 3600 ssh');
+});
+
it('omits native multiplexing options when ssh multiplexing is disabled for a command', function () {
config(['constants.ssh.mux_enabled' => true]);
$server = makeMuxServer();