Manage Providers
Providers you can add:
- Docker (docker)
- Podman (podman)
- Kubernetes (kubernetes)
- Harvester (harvester)
- Apple (apple)
- MicroSandbox (microsandbox)
- Docker Sandboxes (docker-sandbox)
- Lima (lima)
- OrbStack (orbstack)
- SSH (ssh)
- AWS (aws)
- Google Cloud (gcloud)
- Azure (azure)
- Digital Ocean (digitalocean)
List the available providers:
devsy provider list --availableAdd a provider
Devsy Desktop
Open Providers and click Add. The wizard has four steps:
- Select. Pick a preset, or enter a GitHub link, a
provider.yamlURL, or a local path under Provider Source. - Configure. Fill in the options. The form comes from the provider's schema.
- Initialize. Devsy runs the provider init and streams the logs.
- Done. Review the result. A failure shows the underlying error.
Click a provider in the list to edit its settings, change its version, update, re-initialize, rename, set it as default or delete it.
Devsy CLI
devsy provider add dockerUse --name to add the same provider more than once with different options:
devsy provider add aws --name aws-gpu -o AWS_INSTANCE_TYPE=p3.8xlargeFrom GitHub. Devsy downloads provider.yaml from the latest release with your local HTTPS credentials, so private repositories work. Add @ and a tag to use another release.
devsy provider add devsy-org/devsy-provider-terraform
devsy provider add my-org/my-repo@v0.0.1From a local path or URL.
devsy provider add ../devsy-provider-mock/provider.yaml
devsy provider add https://github.com/devsy-org/devsy-provider-ssh/releases/download/v0.0.3/provider.yamlHarvester
devsy provider add harvesterThe Harvester provider needs a cluster kubeconfig, an imported guest image, and a VM network reachable from the Devsy client. The guest must run SSH and Docker. See the provider repository for cloud-init and image selection setup.
MicroSandbox
Install the external provider from its release manifest:
devsy provider add --name microsandbox-external https://github.com/devsy-org/devsy-provider-microsandbox/releases/latest/download/provider.yamlA successful add initializes the provider and makes it the default. To install it without initialization or changing the default, add --use=false and then run devsy provider init microsandbox-external before creating a workspace.
The MicroSandbox guide covers requirements, configuration and runtime compatibility. Choose another name if microsandbox-external already exists.
Existing built-in installations. The built-in MicroSandbox provider is deprecated. Existing configurations are not migrated automatically. To switch one to the external provider, run:
devsy provider set-source <name> https://github.com/devsy-org/devsy-provider-microsandbox/releases/latest/download/provider.yamlCurrent Devsy versions also accept builtin:microsandbox to select the deprecated built-in provider explicitly:
devsy provider add builtin:microsandbox --name legacy-microsandbox --use=falseAfter initialization, the switched provider becomes the default. To restore the previous default, run devsy provider use <previous-name>. If initialization fails, the new source stays selected. Fix the cause and run devsy provider init <name>, or set the previous source again.
Docker Sandboxes
Install the standalone sbx CLI and sign in. See the Docker Sandboxes guide for the prerelease manifest, host availability, and recovery instructions.
Set provider options
Each provider has its own options. In the desktop app, open Providers and click Edit on a provider. With the CLI, set options when you add or initialize:
devsy provider add <provider-name> -o KEY=value
devsy provider init <provider-name> -o KEY=valueList the options and their current values:
devsy provider get <provider-name>Change one later:
devsy provider set <provider-name> --option KEY=VALUEKubernetes registry access
For digest-pinned prebuilt images on Kubernetes, configure cluster registry access without client credentials.
Docker provider
Devsy follows the Docker CLI rules for contexts and daemon endpoints. It uses your existing Docker config.json and contexts, including those from Docker Desktop, OrbStack or a remote endpoint.
Devsy picks the connection in the same order as the Docker CLI:
DOCKER_CONTEXTDOCKER_HOST- The active context in
$DOCKER_CONFIG/config.json, or~/.docker/config.jsonwhenDOCKER_CONFIGis not set - The local socket,
unix:///var/run/docker.sock
Set DOCKER_CONTEXT or DOCKER_HOST as a provider option or as an environment variable:
devsy provider set docker -o DOCKER_CONTEXT=<context-name>
devsy provider set docker -o DOCKER_HOST=ssh://user@docker-hostFor a remote TCP daemon with mutual TLS, set DOCKER_TLS_VERIFY=1 and point DOCKER_CERT_PATH at your client certificates.
Rancher Desktop
Rancher Desktop works with the Docker provider when it uses the Moby engine. If you use containerd, switch to Moby. On macOS Devsy looks for the CLI at ~/.rd/bin/docker when docker is not on your PATH. To set both values yourself:
devsy provider set docker -o DOCKER_PATH="$HOME/.rd/bin/docker"
devsy provider set docker -o DOCKER_CONTEXT=rancher-desktopSingle machine
By default each workspace gets its own machine. To share one machine between all workspaces on a provider, turn on Reuse machine in the provider's options in the desktop app, or run:
devsy provider init <provider-name> --single-machineDefault provider
Devsy uses the default provider for workspaces that do not name one. Set it in the provider's options in the desktop app, or run:
devsy provider use <provider-name>Update a provider
List available versions. Add --prerelease to include pre-releases, or --no-cache to skip the version cache.
devsy provider versions <name>Fetch the provider's source again. Registry entries and unpinned GitHub repositories resolve to the latest release. A pinned tag fetches that version. Local paths and direct provider.yaml URLs reload the file.
devsy provider set-source <name>Pin a version, or replace the source:
devsy provider set-source <name> --version v0.2.0
devsy provider set-source <name> my-org/my-repo
devsy provider set-source <name> https://path/to/provider.yaml
devsy provider set-source <name> ../path-to/provider.yamlIn the desktop app, use the provider's Select version, Update and Initialize actions.
Workspaces reference a provider by name and do not pin its version. Devsy looks up the named provider when it loads a workspace.
Provider icons
A provider can supply its own logo through icon and iconDark in its provider.yaml. Desktop shows it on the provider card and in the setup flow. Develop a provider explains where relative image paths point and which formats and sizes are accepted.
- Devsy fetches the images when you add a provider, and again on
devsy provider set-sourceor an update. Each provider keeps its images in aprovider-assets/cache next to its configuration, so a restart or an offline session still shows the selected image. - Listing providers and opening Desktop never download images.
- A provider installed before this feature shows the bundled logo until you update it or run
devsy provider set-source <name>. - Missing or unusable artwork does not block adding, updating or cloning a valid provider. Desktop shows the bundled logo for the provider's name, or a generic placeholder.
- In dark mode, Desktop uses the dark image if the provider has one, then the light image. In light mode it uses the light image.
- Cloning copies cached images and revision metadata into the new provider, and renaming keeps them. Deleting the original provider does not remove the clone's cached logo.
Remove a provider
In the desktop app, open the provider and click Delete, then confirm. The delete fails while a workspace uses the provider. With the CLI:
devsy provider delete <provider-name>Delete or move the provider's workspaces first. Otherwise the CLI refuses the delete.
Rename a provider
devsy provider rename <current-name> <new-name>Workspaces, machines, options and the default setting move to the new name. If a step fails, Devsy rolls back the rename.
- The new name must be unique and can use lowercase letters, numbers, and dashes, up to 32 characters.
- Platform providers cannot be renamed.
- Renaming can stop running workspaces that use the provider.
In the desktop app, click Rename on the provider, enter the new name, and submit.