Skip to content

docs: document definition of workspace activity #16941

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 21, 2025
Merged

docs: document definition of workspace activity #16941

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5e72d54
draft improvements to workspace activity
EdwardAngert Mar 14, 2025
4e2a304
rephrase pty to reconnection
EdwardAngert Mar 14, 2025
48f5d01
replace quotes with bold
EdwardAngert Mar 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions docs/admin/templates/managing-templates/schedule.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,7 @@ Template [admins](../../users/index.md) may define these default values:
stops it.
- [**Autostop requirement**](#autostop-requirement): Enforce mandatory workspace
restarts to apply template updates regardless of user activity.
- **Activity bump**: The duration of inactivity that must pass before a
workspace is automatically stopped.
- **Activity bump**: The duration by which to extend a workspace's deadline when activity is detected (default: 1 hour). The workspace will be considered inactive when no sessions are detected (VSCode, JetBrains, Terminal, or SSH). For details on what counts as activity, see the [user guide on activity detection](../../../user-guides/workspace-scheduling.md#activity-detection).
- **Dormancy**: This allows automatic deletion of unused workspaces to reduce
spend on idle resources.

Expand Down
53 changes: 36 additions & 17 deletions docs/user-guides/workspace-scheduling.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,18 +37,37 @@ days of the week your workspace is allowed to autostart.
Use autostop to stop a workspace after a number of hours. Autostop won't stop a
workspace if you're still using it. It will wait for the user to become inactive
before checking connections again (1 hour by default). Template admins can
modify the inactivity timeout duration with the
[inactivity bump](#inactivity-timeout) template setting. Coder checks for active
connections in the IDE, SSH, Port Forwarding, and coder_app.
modify this duration with the **activity bump** template setting.

![Autostop UI](../images/workspaces/autostop.png)

## Inactivity timeout
## Activity detection

Workspaces will automatically shut down after a period of inactivity. This can
be configured at the template level, but is visible in the autostop description
Workspaces automatically shut down after a period of inactivity. The **activity bump**
duration can be configured at the template level and is visible in the autostop description
for your workspace.

### What counts as workspace activity?

A workspace is considered "active" when Coder detects one or more active sessions with your workspace. Coder specifically tracks these session types:
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I want to add something like "saving changes to code counts as activity," which I think is true, but it seems like that might be oversimplified. Is there a good single-(noncomplex)-sentence summary we can add here?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That would be really nice but as far as I understand our activity tracking is based on network usage and doesn't count file activity.
I am not sure who is the right person to confirm this.
Maybe @deansheather?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@f0ssel I've realized I don't know what state we left things in re: the workspace activity refactor. Can you look at this section and comment whether it's accurate regarding the code as it exists today?


- **VSCode sessions**: Using code-server or VS Code with a remote extension
- **JetBrains IDE sessions**: Using JetBrains Gateway or remote IDE plugins
- **Terminal sessions**: Using the web terminal (including reconnecting to the web terminal)
- **SSH sessions**: Connecting via `coder ssh` or SSH config integration

Activity is only detected when there is at least one active session. An open session will keep your workspace marked as active and prevent automatic shutdown.

The following actions do **not** count as workspace activity:

- Viewing workspace details in the dashboard
- Viewing or editing workspace settings
- Viewing build logs or audit logs
- Accessing ports through direct URLs without an active session
- Background agent statistics reporting

To avoid unexpected cloud costs, close your connections, this includes IDE windows, SSH sessions, and others, when you finish using your workspace.

## Autostop requirement

> [!NOTE]
Expand Down Expand Up @@ -79,13 +98,13 @@ stopped due to the policy at the **start** of the user's quiet hours.

## Scheduling configuration examples

The combination of autostart, autostop, and the inactivity timer create a
The combination of autostart, autostop, and the activity bump create a
powerful system for scheduling your workspace. However, synchronizing all of
them simultaneously can be somewhat challenging, here are a few example
configurations to better understand how they interact.

> [!NOTE]
> The inactivity timer must be configured by your template admin.
> The activity bump must be configured by your template admin.

### Working hours

Expand All @@ -95,14 +114,14 @@ a "working schedule" for your workspace. It's pretty intuitive:
If I want to use my workspace from 9 to 5 on weekdays, I would set my autostart
to 9:00 AM every day with an autostop of 9 hours. My workspace will always be
available during these hours, regardless of how long I spend away from my
laptop. If I end up working overtime and log off at 6:00 PM, the inactivity
timer will kick in, postponing the shutdown until 7:00 PM.
laptop. If I end up working overtime and log off at 6:00 PM, the activity bump
will kick in, postponing the shutdown until 7:00 PM.

#### Basing solely on inactivity
#### Basing solely on activity detection

If you'd like to ignore the TTL from autostop and have your workspace solely
function on inactivity, you can **set your autostop equal to inactivity
timeout**.
function on activity detection, you can set your autostop equal to activity
bump duration.

Let's say that both are set to 5 hours. When either your workspace autostarts or
you sign in, you will have confidence that the only condition for shutdown is 5
Expand All @@ -114,10 +133,10 @@ hours of inactivity.
> Dormancy is an Enterprise and Premium feature.
> [Learn more](https://coder.com/pricing#compare-plans).

Dormancy automatically deletes workspaces which remain unused for long
durations. Template admins configure an inactivity period after which your
workspaces will gain a `dormant` badge. A separate period determines how long
workspaces will remain in the dormant state before automatic deletion.
Dormancy automatically deletes workspaces that remain unused for long
durations. Template admins configure a dormancy threshold that determines how long
a workspace can be inactive before it is marked as `dormant`. A separate setting
determines how long workspaces will remain in the dormant state before automatic deletion.

Licensed admins may also configure failure cleanup, which will automatically
delete workspaces that remain in a `failed` state for too long.
Loading