Devsy
Developing Providers

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 driver

The Docker driver is the default. Devsy runs the container defined in a devcontainer.json through Docker inside the provider environment. For machine providers, that environment is a VM.

Optional settings:

  • path: where to find the Docker CLI or a replacement, such as Podman. Defaults to docker.
  • install: whether to install Docker in the target environment
  • builder: which docker builder to use
  • runtime: the container runtime, docker, podman, or nerdctl. When empty, Devsy detects the runtime from the binary at path.
  • elevation: run docker commands through a privilege-elevation helper. Use it for a rootful daemon whose socket the current user cannot access. One of pkexec, sudo, doas, or none (default).
  • helperImage: the helper image for volume operations. If empty, Devsy uses 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 driver

The Kubernetes driver deploys the workspace to a Kubernetes cluster. A provider can start a remote cluster or namespace, connect to it, and create the workspace there. Devsy also ships a default Kubernetes provider that uses the local Kubernetes config file.

Options for the Kubernetes driver:

  • kubernetesContext: kube context to use. If empty, Devsy uses the current context.
  • kubernetesConfig: path to the kube config file. If empty, Devsy uses the default config or $KUBECONFIG.
  • kubernetesNamespace: namespace to use. If empty, Devsy uses the current namespace or the default namespace.
  • kubernetesPullSecretsEnabled: if true, Devsy creates Kubernetes pull secrets from injected Docker credentials, for private registries.
  • podTimeout: how long to wait for the workspace pod to start, e.g. 10m
  • createNamespace: if true, Devsy tries to create the namespace
  • clusterRole: if set, Devsy creates a role binding for the cluster role. Use it when the workspace container needs Kubernetes access.
  • serviceAccount: if set, the dev container uses this service account.
  • architecture: CPU architecture of the workspace pod, e.g. amd64 or arm64. If empty, Devsy detects it from the cluster nodes. It fails if the cluster mixes architectures.
  • imageConfigFile: path to a versioned JSON file with the digest-pinned image reference, platform, and OCI config for the devcontainer.json image. When set, Devsy reads the user, env, entrypoint, cmd, and devcontainer.metadata label from the file instead of the registry. See Starting workspaces without registry access.
  • inactivityTimeout: deprecated fallback for agent.containerInactivityTimeout. Set agent.containerInactivityTimeout for new providers.
  • storageClass: storage class for the persistent volume claim
  • diskSize: default persistent volume size, e.g. 10Gi
  • pvcAccessMode: access mode for the persistent volume claim, e.g. RWO, ROX, RWX or RWOP
  • pvcAnnotations: annotations for the main workspace PVC
  • nodeSelector: node selector for the workspace pod, e.g. my-label=value,my-label-2=value-2
  • resources: requests and limits for the workspace container, e.g. requests.cpu=500m,limits.memory=5Gi
  • workspaceVolumeMount: path where the workspace volume is mounted. Defaults to the root of the workspace source code.
  • podManifestTemplate: pod manifest template, inline YAML or a file path, used as the base for the Devsy pod
  • labels: labels for the workspace pod, e.g. devsy.sh/example=value,devsy.sh/example2=value2
  • strictSecurity: clears the hardcoded runAsUser, runAsGroup, and runAsNonRoot fields. Capabilities and privileged stay. The cluster assigns the container UID and GID instead of Devsy forcing root. Unless podManifestTemplate sets hostUsers, this also sets hostUsers: false. That satisfies OpenShift restricted-v3.
  • agentSecurityContext: inline YAML or a file path for a corev1.SecurityContext. Devsy merges it field by field onto the workspace and init containers, overriding its defaults. It sets hostUsers: false unless podManifestTemplate supplies it. A matching named container in podManifestTemplate takes precedence.
  • agentInstallPath: where the agent binary is installed in the devsy and devsy-init containers. The default, /usr/local/bin/devsy, requires root to write. When running non-root, set a path under a writable mount, such as the workspace volume.
  • kubernetesUserNamespaces: maps the pod UIDs into a Linux user namespace by setting hostUsers: false, unless podManifestTemplate already sets it. 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.

On OpenShift, the default security context (fixed runAsUser and runAsGroup) fails the restricted-v2 and restricted-v3 SCCs, which assign UIDs and GIDs from a per-namespace range. Set strictSecurity: "true", set agentSecurityContext, or override the container's securityContext with a named container in podManifestTemplate. Also set agentInstallPath to a path under a writable mount, because a non-root container cannot write the default /usr/local/bin/devsy.

Devsy builds images in Kubernetes without Docker through the dockerless build path (agent.dockerless.disabled / agent.dockerless.image).

Starting workspaces without registry access

For a prebuilt image in devcontainer.json, the Kubernetes driver can read the image configuration from a local file instead of requesting it from the registry. See Kubernetes registry access for the file format, setup, and limitations.

A driver that supports supplied image details implements the ImageDetails capability method. It takes an ImageDetailsRequest with ImageName and UnsupportedReason and returns validated ImageDetails or an error. It returns nil, nil only when the option is unset. Validate the configured input for the requested image before use. Unsupported combinations and invalid files return errors and must not fall back to registry inspection.

Example Kubernetes provider

Example provider that runs a workspace in the current kube context:

name: simple-kubernetes
version: v0.0.1
agent:
  containerInactivityTimeout: 10m
  local: true
  driver: kubernetes
  kubernetes:
    diskSize: 20Gi
    createNamespace: true
exec:
  command: |-
    "${DEVSY}" internal sh -c "${COMMAND}"

Add the provider with devsy provider add ./simple-kubernetes.yaml.

Apple driver

The Apple driver runs the workspace as a Linux container with Apple's container runtime. It needs macOS 26+ on Apple silicon. The built-in apple provider uses this driver.

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 driver

The Microsandbox driver boots the devcontainer image as a hardware-isolated microVM with microsandbox. This built-in driver is deprecated. New installs should 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 outbound public network access from the microVM.
  • ephemeral: boot from a tmpfs root disk, so disk state is discarded when the VM stops.
  • workspaceHostPermissions: mirror (default) copies 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. Recreating discards the VM root disk, 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 driver

The custom driver lets a provider run the devcontainer lifecycle through 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 driver

driver: external runs a runtime plugin that speaks the Devsy runtime protocol. The protobuf schema and the plugin SDK are 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. Devsy applies no shell or option substitution.
  • imageBackend: the Devsy-side image backend, docker (default) or none. 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 each operation, Devsy verifies the executable's bytes. Devsy 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 permission on Unix.

The plugin is trusted provider code. It runs with the agent user's access and inherits the agent host's environment. Avoid logging that environment.

On this page