Devsy
Developing Providers

Provider Agent

Devsy runs a copy of its CLI as an agent in the provider environment. For a remote provider, it places the binary on the remote machine. A local provider uses the host's binary. The agent deploys the workspace, forwards credentials, runs the SSH server, and manages inactivity shutdown.

Configure it in the agent section of provider.yaml. This example uses a local Docker daemon:

agent:
  local: true
  driver: docker

This section can use option values.

  • path: path to the agent binary in the provider environment. If omitted, a local agent uses the current executable; a remote agent uses Devsy's default install path.
  • local: set to true when the agent runs on the user's machine. Leave it unset or false for a remote machine.
  • driver: how the container is deployed. One of docker (default), kubernetes, apple, microsandbox, custom or external. See Drivers.
  • inactivityTimeout: how long an idle machine runs before Devsy stops it. Machine providers only.
  • containerInactivityTimeout: idle period monitored by the container daemon, as a Go duration such as 10m. For Kubernetes, an empty value falls back to the deprecated agent.kubernetes.inactivityTimeout. If both fields are set, their durations must match. Clear both fields or set both to 0 to disable the timeout. For Kubernetes, expiry ends the pod. A detached Docker or Podman daemon does not stop its container when the timer expires.
  • injectGitCredentials, injectDockerCredentials: whether to forward those credentials into the environment. The context's credential-forwarding settings override these provider values. See Credentials.
  • exec.shutdown: the command that stops the machine once it is idle. Option values are available in it.
  • binaries: helper binaries for exec.shutdown. Declare them under agent.binaries, using the format in Provider binaries.

Docker management policy

For the docker driver, the agent.docker section controls how Devsy manages Docker on the agent machine:

agent:
  local: false
  driver: docker
  docker:
    path: docker
    install: false
    configureDaemon: false

Set install: false when the provider supplies a Docker CLI. If that executable is missing, Devsy reports an error instead of installing Docker. An existing executable remains usable. With install unset or true, Devsy retains its existing installation behavior.

Set configureDaemon: false when the provider owns the Docker daemon, including a private daemon inside a VM. Devsy then does not read or modify the daemon configuration for its management step and does not reload the daemon. With configureDaemon unset or true, Devsy retains its existing behavior of configuring the daemon for a remote Docker agent. Local agents are not configured by this step. These settings accept provider option templates, which must resolve to valid boolean values before the agent starts Docker setup. This policy controls Devsy's daemon management, not arbitrary commands a user runs inside a devcontainer.

Stopping idle environments

Inactivity shutdown depends on the provider and driver. Start a stopped workspace with devsy workspace up. State survives only if the provider keeps the storage. A shutdown command that deletes the machine must keep workspace data elsewhere, for example on a persistent volume.

Non-machine providers

Set the timeout with containerInactivityTimeout.

With the kubernetes driver, the Devsy daemon is the pod's main process. SSH sessions, hooks, and setup register with the daemon over a Unix socket in the pod before they run, and the daemon pauses the idle timer while they stay registered. If the connection drops, the registered work aborts. When the workspace stays idle for the timeout, the daemon exits, which ends the pod and keeps its volume. Other container drivers start a detached daemon whose exit does not stop the container. See Auto-Inactivity Timeout for activity rules and pod-layout restrictions.

Any UID in the same container can block inactivity through a live activity connection. Only root and the daemon's UID can change setup or timeout policy. Do not expose the activity socket outside its container.

Machine providers

Stopping only the container leaves the VM running and billed. Define agent.exec.shutdown with a command that stops or deletes the machine on the cloud side, and set inactivityTimeout. If the command needs a helper binary, declare it under agent.binaries. Check the provider's API and storage policy before choosing between stopping and deleting the machine.

On this page