Auto-Inactivity Timeout
Providers can stop idle workspaces to save resources. Start a stopped workspace with devsy workspace up. Workspace data persists if the provider preserves storage.
Configure the timeout
Apple, Docker, Kubernetes, Microsandbox, and Podman have an INACTIVITY_TIMEOUT option. Values use Go duration format, such as 10m or 1h. See Set provider options.
Defaults when the option is unset:
- Machine providers use the
inactivityTimeoutvalue from the provider, or 20 minutes if the provider sets none. - Docker, Kubernetes, Podman, Apple, and Microsandbox containers never time out when
INACTIVITY_TIMEOUTis unset or0.
How it works
Kubernetes: The Devsy daemon is the main process of the workspace pod. Setup keeps a connection to the daemon open and counts as activity until setup ends. After the timeout passes with no activity, the daemon stops its child processes, logs that the timeout was reached, and exits. The pod ends and the workspace volume stays. See Kubernetes.
Docker, Podman, Apple, and Microsandbox: A daemon in the container watches for activity. For Microsandbox, Devsy also passes the timeout to the microsandbox CLI as --idle-timeout.
Apple provider
The Apple provider option describes the timeout as deleting the container instead of stopping it. Deleting a container loses files outside mounted volumes.
Machine providers: A Devsy daemon runs on the VM. When every workspace on the machine has been idle for the timeout, the daemon runs agent.exec.shutdown, a command the provider defines. State persists only if the provider keeps storage.
See the agent guide for how providers implement this, and Machine diagnostics for debugging.
What counts as activity
A workspace is active while either of these holds:
- A tracked
devsy workspace sshsession is connected. Devsy records activity when the session connects, periodically while it stays open, and when it ends. The idle period starts at disconnect. - Setup is running: the synchronous
devsy workspace upsetup, deferred lifecycle hooks, andpostAttachCommand.
CPU use and processes you start yourself do not count. For example, nohup make & in a closed session does not keep the workspace running.
The daemon checks idle time about once a second, so a workspace stops a few seconds after the timeout passes.
On Kubernetes, SSH sessions and hooks register with the daemon before they do work and stay active while their connection lasts. If the daemon connection is lost, Devsy cancels the protected work. Failed activity-file writes or a full disk cannot hide live work.
Other container daemons read legacy activity-file timestamps. If a daemon cannot read the activity file, it logs an error and the timeout stays inactive until the file is readable.
Managed clients read the daemon configuration mounted at /var/run/secrets/devsy/daemon_config. If a managed workspace cannot find it, Devsy returns an error and does not fall back to file heartbeats. Linux process-start identity must stay readable through /proc, or registration fails and Devsy cancels the protected connection.
Any Unix user in the same container can block idle stop through a live activity connection. Users in a container are not isolated from each other. Only root and the daemon's UID can change setup and timeout policy.
Kubernetes
Set INACTIVITY_TIMEOUT on the Kubernetes provider, such as 1h. In a custom provider, the deprecated inactivityTimeout field under agent.kubernetes is an alias. Devsy uses it only when containerInactivityTimeout is empty. If both are set, they must match.
The timeout is off when it is empty or 0, when shutdownAction is none, or when devsy workspace up runs with --disable-daemon. A negative or unparsable value is an error. Kubernetes rejects stopCompose with a positive timeout.
--disable-daemon applies to that one command. The next up without the flag uses the provider timeout and shutdown action again.
When the saved run configuration changes, including a recreate that changes the workspace image or Dockerless topology, the Kubernetes credentials on your machine need update permission on persistentvolumeclaims in the workspace namespace. Devsy updates only the run-information annotation, before it changes daemon configuration or creates the new pod. Unchanged run options cause no update. Devsy does not change your RBAC roles. If the update is denied or conflicts, Devsy stops and keeps the volume and its previous record. An explicit --recreate may already have stopped the old pod.
When the workspace stops:
- The pod can stay in the
SucceededorFailedphase until the nextdevsy workspace upordevsy workspace stop. The nextupdeletes the finished pod and creates a new one on the same persistent volume claim. No recreate flag is needed. - Files on the workspace volume persist. Files in the container filesystem outside mounted volumes are lost, because the new pod starts from the image.
devsy workspace stopdeletes the pod through the Kubernetes API from your machine. The pod gets no Kubernetes credentials of its own.
When WORKSPACE_VOLUME_MOUNT selects a parent of the workspace folder, the pod mounts that parent. Reuse and resume keep the same workspace subdirectory on the volume.
Pod layout rules:
- One regular
devsycontainer, any number of normal init containers, and native sidecars (init containers withrestartPolicy: Always). Native sidecars end with the pod. - With a positive timeout, Devsy rejects extra regular containers in
spec.containers, such as those from a pod manifest template or an admission webhook. The pod would keep running while they run. The error names the containers. Without a timeout, or withshutdownAction: none, extra containers are allowed. - With a positive timeout, the Devsy daemon must be the main process of the container. Devsy rejects a
devcontainer.jsonwithoverrideCommand: falseand an image entrypoint or command. - Dockerless builds do not support a positive timeout.
Devsy checks the pod manifest template against the merged shutdown action and --disable-daemon before an explicit --recreate stops the existing pod. It can check admission-webhook changes only after it creates the pod.
Layout validation
The rules above do not cover every pod layout. Test these on a non-production workspace before you rely on the timeout: restricted non-root security, native sidecars or extra init containers, admission-webhook layouts, Devsy Platform routes, and upgrades from an earlier Devsy version.
A pod whose daemon uses an older lifecycle protocol must be replaced once. devsy workspace up reports the incompatible owner and asks you to restart the workspace. Run devsy workspace stop, then devsy workspace up. The persistent volume stays. Replacing the agent binary alone does not upgrade a daemon that already runs in the pod.
Shutdown action
Set shutdownAction in devcontainer.json. It is not a provider option.
noneturns off the container timeout monitor. For machines, it also stopsagent.exec.shutdownfrom running.- Any other value turns on the container timeout monitor. For machines,
agent.exec.shutdownruns when the timeout passes, if the command is set.
When shutdownAction is unset, the default is stopCompose for Compose workspaces and stopContainer for all others. Apart from none, and apart from Kubernetes rejecting stopCompose, the value does not change what the container timeout does.