Limit how long environments can stay idle before auto-stopping. Useful when:
- Controlling cloud infrastructure costs from forgotten environments
- Ensuring resources are available for other team members
- Preventing “never timeout” settings that waste compute
Configuration
Select maximum timeout duration: 30 minutes, 1 hour, 3 hours, 8 hours, or No max (includes “Never”).
Effect on users
Users only see timeout options up to the maximum. For example, with “3 hours” max, options are: 30 min, 1 hour, 3 hours.
When is an environment idle?
An environment is not idle as long as any of the following are true:
- Plain SSH session is open — Any open SSH connection (terminal, SCP, SFTP, tunnels) prevents the environment from going idle, regardless of user interaction. Connection presence alone is enough. Note: VS Code Desktop opens an SSH connection to the environment, but that connection is excluded from activity tracking — VS Code uses its own activity signals instead.
- VS Code is active (Desktop or Browser) — The VS Code extension sends activity signals based on keyboard and mouse interaction. After a short period without interaction, VS Code stops signaling and the environment is considered idle.
- JetBrains Gateway is active — JetBrains sends activity signals based on keyboard and mouse interaction in the IDE. After approximately 5 minutes without interaction, JetBrains stops signaling and the environment is considered idle.
- Ona Agent is running — The environment is not idle while an Ona AI agent session is executing a task.
- CLI keep-alive is active — The
gitpod environment keep-alive command prevents idle as long as a watched process is running (see below).
The following do not prevent an environment from going idle:
- Background processes running inside the environment (builds, servers, cron jobs)
- Port forwarding and shared/exposed port traffic (HTTP requests to forwarded ports)
- File system changes
- CPU or memory usage
Activity is tracked in 5-minute intervals. After your configured timeout elapses, the actual auto-stop may occur several minutes later. For example, with a 30-minute timeout, if you go idle at 2:00 PM the environment may stop around 2:35 PM.
Common scenarios
| Scenario | Will it be considered idle? |
|---|
| VS Code open, idle (Desktop or Browser) | Yes — VS Code stops sending activity signals after a short period without keyboard or mouse interaction |
| JetBrains open, idle | Yes — JetBrains stops sending activity signals after approximately 5 minutes without keyboard or mouse interaction |
| Editor closed, terminal SSH session open | No — an open SSH connection prevents idle |
| All editor/SSH sessions closed, background build running | Yes — background processes do not prevent idle |
| Laptop goes to sleep with VS Code open | Depends — if the sleep duration exceeds the configured timeout, the environment may auto-stop before VS Code can resume. JS timers freeze during sleep, so no activity signals are sent until the laptop wakes |
| Laptop goes to sleep with JetBrains open | Yes — JetBrains stops signaling during sleep, so the environment will auto-stop after the configured timeout |
Keep environment alive during long-running tasks
For long-running tasks like simulations, builds, or data processing that may exceed the timeout, use the CLI keep-alive command to prevent automatic shutdown while a process is running.
# Watch an existing process by PID
gitpod environment keep-alive --pid 1234
# Execute and watch a command
gitpod environment keep-alive -- python simulation.py
# Run in quiet mode (suppress output except errors)
gitpod environment keep-alive -q -- ./long-running-script.sh
| Flag | Description |
|---|
--pid | PID of an existing process to watch |
--interval | Interval between activity signals (default: 5m) |
--source | Source identifier for activity signals |
-q, --quiet | Suppress output except errors |
--environment-id | Environment ID (auto-detected inside environments) |
