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, ornerdctl. When empty, Devsy detects the runtime from the binary atpath. - 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, ornone(default). - helperImage: the helper image for volume operations. If empty, Devsy uses the
DEVSY_HELPER_IMAGEenvironment 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
defaultnamespace. - 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.
amd64orarm64. 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, anddevcontainer.metadatalabel from the file instead of the registry. See Starting workspaces without registry access. - inactivityTimeout: idle time before Devsy stops the pod
- 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,RWXorRWOP - 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, andrunAsNonRootfields. Capabilities andprivilegedstay. The cluster assigns the container UID and GID instead of Devsy forcing root. UnlesspodManifestTemplatesetshostUsers, this also setshostUsers: false. That satisfies OpenShiftrestricted-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 setshostUsers: falseunlesspodManifestTemplatesupplies it. A matching named container inpodManifestTemplatetakes 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, unlesspodManifestTemplatealready sets it. Requires Kubernetes 1.30+ with theUserNamespacesSupportgate enabled (on by default from 1.33), Linux kernel 6.3+, and containerd 2.0+ or CRI-O 1.25+. On clusters without support, sethostUsersthroughpodManifestTemplate.
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 # Pod stops itself after being idle for the 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}"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
containerbinary. Defaults tocontainer. - rosetta: enable Rosetta for x86_64 emulation inside the Linux guest.
- env: a map of environment variables to set when running
containercommands
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.privatekeeps them in microsandbox metadata. - workspaceStatVirtualization:
strict(default) requires host metadata support.relaxedtolerates filesystems without it.offexposes literal host ownership and modes, and cannot be combined withmirror.
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 onPATH. - args: a fixed argument list. Devsy applies no shell or option substitution.
- imageBackend: the Devsy-side image backend,
docker(default) ornone. Withnone, 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.