Drivers

A driver decides how Devsy deploys the workspace container. Set it with driver in the agent section. The default is docker.

Built-in drivers: docker, kubernetes, apple, microsandbox and custom. The external driver runs a runtime plugin and is described below.

Docker DriverCopy Anchor Link

The Docker driver is the default driver that Devsy uses to deploy the workspace container.

This container (specified through a devcontainer.json), is executed through Docker inside the provider environment, for example in a VM in case of Machine Providers.

Some optional configs are available:

• path: where to find the Docker CLI or a replacement, such as Podman. Defaults to docker.
• install: whether to install Docker or not in the target environment
• builder: which docker builder to use
• runtime: explicitly select the container runtime (docker, podman, or nerdctl). When empty, the runtime is auto-detected from the binary at path.
• elevation: optionally run docker commands through a privilege-elevation helper for rootful daemons whose socket the current user can't access. One of pkexec, sudo, doas, or none (default).
• helperImage: overrides the helper image used for volume operations. Empty falls back to the DEVSY_HELPER_IMAGE environment variable, then a built-in default.
• env: a map of environment variables to set when running docker commands, e.g. DOCKER_HOST

Example config:

agent:
  containerInactivityTimeout: 10m
  docker:
    path: /usr/bin/docker
    install: false
    elevation: none
    env:
      DOCKER_HOST: ""

Kubernetes DriverCopy Anchor Link

Instead of Docker, Devsy is also able to use Kubernetes as a Driver, which allows you to deploy the workspace to a Kubernetes cluster instead. For example, this makes it possible to create a provider that spins up a remote Kubernetes cluster (or just a namespace), connects to it, and creates a workspace there. Devsy also has a default Kubernetes provider that uses the local Kubernetes config file to deploy the workspace.

The allowed options for the Kubernetes driver are:

• kubernetesContext: which kube context to use (if empty will use current kube context)
• kubernetesConfig: path to which kube config to use (if empty will use default kube config, or $KUBECONFIG)
• kubernetesNamespace: which namespace to use (if empty will use current namespace or default)
• kubernetesPullSecretsEnabled: if true, Devsy will create Kubernetes pull secrets from injected Docker credentials for private registries
• podTimeout: how long the provider waits for the workspace pod to come up, e.g. 10m
• createNamespace: if true, Devsy will try to create the namespace
• clusterRole: if defined, Devsy will create a role binding for the given cluster role for the workspace container. This is useful if you need Kubernetes access within the workspace container
• serviceAccount: if defined, Devsy will use the given service account for the dev container
• architecture: the CPU architecture to use for the workspace pod, e.g. amd64, arm64. If empty, Devsy inspects the cluster's nodes to auto-detect it (and errors out if the cluster has mixed architectures).
• inactivityTimeout: after how much time to automatically stop the pod due to inactivity
• storageClass: the storage class to use to create the persistent volume claim
• diskSize: the default size for the persistent volume to use, e.g. 10Gi
• pvcAccessMode: the access mode to use for the persistent volume claim, e.g. RWO, ROX, RWX or RWOP
• pvcAnnotations: annotations to add to the main workspace PVC
• nodeSelector: the node selector to use for the workspace pod, e.g. my-label=value,my-label-2=value-2
• resources: resource requests/limits for the workspace container, e.g. requests.cpu=500m,limits.memory=5Gi
• workspaceVolumeMount: overrides the path where the workspace volume is mounted. Defaults to the root of your workspace source code.
• podManifestTemplate: a pod manifest template (inline YAML or a file path) used as the base to build the Devsy pod
• labels: labels to add to the workspace pod, e.g. devsy.sh/example=value,devsy.sh/example2=value2
• strictSecurity: Clears the hardcoded runAsUser/runAsGroup/runAsNonRoot fields (retaining capabilities and privileged), letting the cluster assign the container's UID/GID instead of forcing root. It sets hostUsers: false unless podManifestTemplate explicitly supplies hostUsers; this satisfies OpenShift restricted-v3.
• agentSecurityContext: inline YAML or a file path for a corev1.SecurityContext merged field by field onto the workspace and init containers, overriding Devsy's defaults. Sets hostUsers: false unless podManifestTemplate supplies it. A matching named container in podManifestTemplate takes precedence.
• agentInstallPath: overrides where the agent binary is installed inside the devsy/devsy-init containers. Defaults to /usr/local/bin/devsy, which requires root to write; set this to a path under a writable mount (e.g. the workspace volume) when running non-root.
• kubernetesUserNamespaces: sets hostUsers: false (unless podManifestTemplate already sets it), mapping the pod's UIDs into a Linux user namespace. Requires Kubernetes 1.30+ with the UserNamespacesSupport gate enabled (on by default from 1.33), Linux kernel 6.3+, and containerd 2.0+ or CRI-O 1.25+. On clusters without support, set hostUsers through podManifestTemplate instead.

Example Kubernetes ProviderCopy Anchor Link

Example Kubernetes provider that uses local kubectl to run a workspace in the current kube context:

name: simple-kubernetes
version: v0.0.1
agent:
  containerInactivityTimeout: 10m # Pod will automatically kill itself after timeout
  path: ${DEVSY}
  driver: kubernetes
  kubernetes:
    # kubernetesContext: default
    # kubernetesNamespace: my-namespace-for-devsy
    # clusterRole: ""
    # serviceAccount: ""
    diskSize: 20Gi
    createNamespace: true
exec:
  command: |-
    ${DEVSY} helper sh -c "${COMMAND}"

Then add the provider via devsy provider add ./simple-kubernetes.yaml

Apple DriverCopy Anchor Link

The Apple driver runs the workspace as a Linux container using Apple's native container runtime (macOS 26+, Apple silicon). This is the driver used by the built-in apple provider.

Available options:

• path: where to find the container binary. Defaults to container.
• rosetta: enable Rosetta for x86_64 emulation inside the Linux guest.
• env: a map of environment variables to set when running container commands

agent:
  containerInactivityTimeout: 10m
  driver: apple
  apple:
    path: container
    rosetta: "false"

Microsandbox DriverCopy Anchor Link

The Microsandbox driver boots the devcontainer image as a hardware-isolated microVM using microsandbox. The built-in driver is deprecated. For new installs, use the external MicroSandbox provider.

Options:

• memory, cpus: guest memory in MiB and virtual CPU count. Empty uses the runtime default.
• maxMemory, maxCpus: ceilings for hotplugged memory and CPUs.
• storage: root disk size in GiB. Falls back to the devcontainer's hostRequirements.storage.
• blockEgress: deny the microVM outbound public network access.
• ephemeral: boot from a tmpfs root disk, so disk state is discarded when the VM stops.
• workspaceHostPermissions: mirror (default) mirrors guest permission changes on the workspace mount to the host. private keeps them in microsandbox metadata.
• workspaceStatVirtualization: strict (default) requires host metadata support. relaxed tolerates filesystems without it. off exposes literal host ownership and modes, and cannot be combined with mirror.

Changing the workspace permission policy or the developer identity requires devsy up --recreate. The VM root disk is discarded on recreate, so back up VM-local data first. The host workspace and named volumes persist.

agent:
  containerInactivityTimeout: 10m
  driver: microsandbox
  microsandbox:
    memory: "2048"
    blockEgress: "false"
    workspaceStatVirtualization: "strict"

Custom DriverCopy Anchor Link

The custom driver lets a provider implement the devcontainer lifecycle with its own shell commands. With driver: custom, these commands are required under agent.custom:

• findDevContainer: find an existing devcontainer.
• commandDevContainer: run a command inside it.
• targetArchitecture: print the target architecture.
• runDevContainer, startDevContainer, stopDevContainer, deleteDevContainer: run, start, stop and delete it.

Optional: getDevContainerLogs prints the logs, and canReprovision says whether the devcontainer can be reprovisioned in place.

External DriverCopy Anchor Link

driver: external runs a runtime plugin that speaks the Devsy runtime protocol. The protobuf schema and plugin SDK live in devsy-runtime-sdk.

agent:
  driver: external
  external:
    binary: RUNTIME_DRIVER
    args: ["serve"]
    imageBackend: docker
  binaries:
    RUNTIME_DRIVER:
      - os: linux
        arch: amd64
        path: https://example.com/runtime-driver
        checksum: "<SHA-256 of the extracted executable>"

• binary: the exact key in agent.binaries. It is not a path and is not searched on PATH.
• args: a fixed argument list. No shell or option substitution is applied.
• imageBackend: docker (default) or none. It selects the Devsy-side image backend. With none, prebuild publishing is unavailable.

Every platform entry for the selected binary key requires a SHA-256 checksum.

Agent setup prepares the executable. Before launching each operation, Devsy verifies its bytes and never downloads or removes it. The path is relative to the prepared agent-binaries directory, or an absolute local path. It must resolve to a regular file, with execute access on Unix.

The plugin is trusted provider code and runs with the agent user's access. It inherits the agent host's environment, so avoid logging it.