Manage Providers

Providers you can add:

• Docker (docker)
• Podman (podman)
• Kubernetes (kubernetes)
• Apple (apple)
• MicroSandbox (microsandbox)
• Lima (lima)
• OrbStack (orbstack)
• SSH (ssh)
• AWS (aws)
• Google Cloud (gcloud)
• Azure (azure)
• Digital Ocean (digitalocean)

List what is available from the CLI:

devsy provider list --available

Add a providerCopy Anchor Link

Devsy DesktopCopy Anchor Link

Open Providers and click Add. The wizard has four steps:

1. Select. Pick a preset, or enter a GitHub link, a provider.yaml URL, or a local path under Provider Source.
2. Configure. Fill in the options. The form comes from the provider's schema.
3. Initialize. Devsy runs the provider init and streams the logs.
4. Done. Review the result. A failure shows the underlying error.

Click a provider in the list to edit its settings, switch version, update, re-initialize, rename, set it as default, or delete it.

Devsy CLICopy Anchor Link

devsy provider add docker

devsy provider add microsandbox installs the latest published external MicroSandbox provider from github.com/devsy-org/devsy-provider-microsandbox. The Desktop MicroSandbox preset selects the same source. To install a specific release, append a tag, for example github.com/devsy-org/devsy-provider-microsandbox@v0.1.8.

Existing built-in MicroSandbox installations are listed as Deprecated built-in in Desktop and marked deprecated by devsy provider list. Their names, defaults, options and existing workspaces are unchanged. The label also applies to custom provider definitions that select the built-in MicroSandbox driver; it does not apply to an external provider merely named microsandbox.

For deliberate compatibility use, builtin:microsandbox explicitly selects the deprecated implementation:

devsy provider add builtin:microsandbox --name legacy-microsandbox --use=false

Adding the external provider does not migrate an installed provider with the same name. Existing records retain their source until an explicit provider set-source operation. See the runtime rollout decision for the tested migration behavior and its compatibility limits.

Use --name to add the same provider more than once with different options:

devsy provider add aws --name aws-gpu -o AWS_INSTANCE_TYPE=p3.8xlarge

From GitHub. Devsy downloads the provider.yaml from the latest release. It uses your local HTTPS credentials, so private repositories work. Add @ and a tag for another release.

devsy provider add devsy-org/devsy-provider-terraform
devsy provider add my-org/my-repo@v0.0.1

From 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.yaml

Set provider optionsCopy Anchor Link

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=value

List the options and their current values:

devsy provider get <provider-name>

Change one later:

devsy provider set <provider-name> --option KEY=VALUE

Docker providerCopy Anchor Link

Devsy follows the Docker CLI's rules for contexts and daemon endpoints. It keeps your existing Docker config.json and contexts, so contexts from Docker Desktop, OrbStack, or a remote endpoint keep working.

Devsy picks the connection in the same order as the Docker CLI:

1. DOCKER_CONTEXT
2. DOCKER_HOST
3. The active context in $DOCKER_CONFIG/config.json, or ~/.docker/config.json when DOCKER_CONFIG is not set
4. 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-host

For a remote TCP daemon with mutual TLS, set DOCKER_TLS_VERIFY=1 and point DOCKER_CERT_PATH at your client certificates.

Rancher DesktopCopy Anchor Link

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. You can set both values yourself:

devsy provider set docker -o DOCKER_PATH="$HOME/.rd/bin/docker"
devsy provider set docker -o DOCKER_CONTEXT=rancher-desktop

Single machineCopy Anchor Link

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-machine

Default providerCopy Anchor Link

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 providerCopy Anchor Link

Show available versions. Add --prerelease to include pre-releases and --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 that source.

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.yaml

In the desktop app, use the provider's Select version, Update, and Initialize actions.

Devsy prepares the replacement provider’s installation binaries (binaries) before changing the installed provider. Runtime binaries declared under agent.binaries are prepared later by workspace operations. A download, checksum, archive, or cancellation error during preparation keeps the installed binaries, provider settings, initialization state, and workspace associations intact. Absolute local binary paths are checked without modifying the referenced files. References into the managed binaries directory must also match the prepared result; ambiguous aliases into that directory are rejected before publication.

If publishing the prepared update fails, Devsy attempts to restore the previous files. If restoration fails, the error identifies retained recovery artifacts; keep those files for recovery. This does not guarantee recovery after a process or machine crash. Initialization runs after publication: an initialization failure leaves the new provider installed and available for another initialization attempt.

Existing workspaces keep the provider version they were created with. Recreate one with devsy workspace up <name> --recreate to pick up the new version.

Remove a providerCopy Anchor Link

In the desktop app, click the trash icon on the provider. If a workspace uses it, Devsy asks you to remove that workspace first. With the CLI:

devsy provider delete <provider-name>

Rename a providerCopy Anchor Link

devsy provider rename <current-name> <new-name>

Workspaces, machines, options, and the default setting follow the new name. If any step fails, Devsy rolls the rename back.

• The new name must be unique and can use lowercase letters, numbers, and dashes, up to 32 characters.
• Pro providers cannot be renamed.
• Stop the provider's workspaces first.

In the desktop app, edit Provider Name in the provider's configuration and click Update Options.