Devsy
Developing Providers

Build a provider

A provider is a program described by a provider.yaml file. Devsy reads the manifest and calls the commands it defines to create and reach an environment.

Recommended reading

A minimal provider

This provider runs workspaces through Docker on your machine. Install Docker and start its daemon before trying it.

name: my-first-provider
version: v0.0.1
agent:
  local: true
  driver: docker
exec:
  command: |-
    "${DEVSY}" internal sh -c "${COMMAND}"

Save it as provider.yaml. Run these commands in your host terminal:

devsy provider add ./provider.yaml
devsy workspace up github.com/microsoft/vscode-remote-try-go

Adding the provider makes it the default for new workspaces. The second command clones the sample repository and starts its devcontainer. Existing workspaces keep their provider.

Sections of provider.yaml

  • name: required, at most 32 lowercase letters, numbers, or hyphens. version is optional; when set, use a semantic version such as v0.0.1. description is optional and shown in the Desktop app.
  • exec: the commands Devsy runs to reach and manage the environment.
  • options: settings the user can configure. Devsy passes them to commands as environment variables.
  • binaries: helper binaries Devsy downloads for the provider.
  • agent: how the agent runs in the environment: the driver, inactivity timeout, and credentials.
  • icon and iconDark: optional images the Desktop app shows for the provider.

exec

The command, init, create, delete, start, stop, status and describe entries are POSIX shell scripts or command arrays. For standard providers, only command is required. Proxy and daemon providers use their own exec fields instead. cancellation is an execution policy, not a script.

An array with one element is parsed as a shell script, not as an executable path. For example, ["/opt/provider tool"] runs /opt/provider with the argument tool. Quote the path inside that script or provide a multi-element array to run a path that contains spaces.

  • command: runs a command in the environment. Devsy uses it to inject itself, and sends all traffic through its standard input and output. Devsy fills in the ${COMMAND} placeholder.
  • init: checks that the options are valid and the provider is ready. Devsy runs it when options change.
  • create, delete: create and delete a machine. Define both or neither. Defining create makes this a machine provider.
  • start, stop: start and stop a machine. Define both or neither. These require create and status.
  • status: prints one of Running, Busy (wait and check again), Stopped or NotFound.
  • describe: prints a text description of the machine.
  • cancellation: omit it to use the default cancellation behavior, or set file to give provider commands a cooperative cleanup window.

A standard provider without create is a non-machine provider and uses only command and init. The cancellation policy applies to both machine and non-machine providers.

Handle cancellation

With exec.cancellation: file, Devsy sets DEVSY_PROVIDER_CANCEL_FILE to a private marker path that does not exist yet. Do not set or override this reserved variable.

When the caller cancels, Devsy creates the marker. Your command has up to 10 seconds to stop accepting work, cancel its owned processes, clean up, and exit.

If a single-string shell command is still blocked, Devsy asks its shell supervisor to stop and reap direct children. It allows up to another 5 seconds for an authenticated acknowledgement, then kills an unresponsive helper. A missing or forged acknowledgement, including after an abrupt helper exit, is reported as an unclean shutdown. A provider-written acknowledgement file does not prove cleanup finished.

Devsy waits for the invocation to finish and returns the caller's cancellation error even if cleanup succeeds. It does not kill the provider's process group or unrelated daemons.

The supervisor also stops and reaps direct children when the script finishes normally. A job started with & cannot outlive that invocation. A detached descendant can, so your provider must manage it. Use the backend's detached operation for durable services.

Handle command streams

Cancellation cannot interrupt an arbitrary blocked reader or writer. File cancellation mode works with finite or nonblocking streams, direct file input handles, or blocking streams that their owner unblocks when the original calling context is cancelled.

  • Drain or unblock stdout and stderr on cancellation, including file-backed pipes. Devsy may wrap a direct *os.File output for redaction, so it can still block after the child exits.
  • Devsy does not close caller-owned input or global standard input. Machine command transports close their own pipe endpoints when the original context is cancelled.
  • Keep draining output after standard input reaches EOF. Input and output can close independently.

Windows compatibility

On Windows, Devsy runs these scripts in an emulated shell. It does not provide grep or sed. Put that logic in a helper binary or require the user to install those tools.

Example from the SSH provider:

exec:
  init: |-
    OUTPUT=$(ssh -oStrictHostKeyChecking=no -p ${PORT} ${EXTRA_FLAGS} "${HOST}" 'sh -c "echo DevsyTest"')
    if [ "$OUTPUT" != "DevsyTest" ]; then
      >&2 echo "Unexpected ssh output. Check the SSH host and options."
      exit 1
    fi
  command: |-
    ssh -oStrictHostKeyChecking=no -p ${PORT} ${EXTRA_FLAGS} "${HOST}" "${COMMAND}"

Icons

A provider can ship its own logo. Set icon and, optionally, iconDark in provider.yaml:

name: my-first-provider
version: v0.0.1
icon: assets/logo.svg
iconDark: assets/logo-dark.svg

Devsy downloads the images when the provider is added or updated and stores them in a provider-assets/ directory next to the provider's configuration. The Desktop app reads them from disk, so cached logos work offline. Cloning copies the cached files into the new installation. If the source cache is missing or corrupt, the clone uses the bundled logo or a placeholder.

Devsy does not look for logo.svg or read the repository homepage. Only the two fields above count.

Where a relative path points

Devsy resolves a relative path against the source the provider was installed from, not the provider's install directory.

Installed fromassets/logo.svg means
github.com/owner/repo (no tag)The file in the repository root at the release Devsy selected for this install (the latest stable release when you add it). Never main.
github.com/owner/repo@v1.2.3The file in the repository root at tag v1.2.3.
Direct URL, such as https://host/path/provider.yamlhttps://host/path/assets/logo.svg. A release-download URL therefore points at a sibling release asset.
Raw GitHub URLNormal URL resolution, so the ref and directory in that URL are kept.
Local provider.yamlThe file next to the manifest. Symlinks and .. may not leave the manifest directory.
Built-in providerNo repository lookup. Absolute icon URLs or the bundled logo.

Devsy also accepts absolute http:// and https:// URLs and downloads them with the other images, so the Desktop app needs no network access to show them.

A relative path must not contain a backslash, a NUL byte, a leading /, a // authority, or a .. segment that leaves the manifest root. Devsy also rejects encoded forms such as %2e%2e. Subdirectories and Unicode file names work. Devsy rejects javascript:, file:, and data: references.

GitHub release manifests

For a GitHub source, Devsy installs the provider.yaml attached to the release and treats the release as the repository root at its tag. Commit the image files before you tag the release, so the tag contains both the manifest and the images.

Formats and limits

  • PNG, JPEG, WebP, and SVG. Devsy checks the file content, not only the extension. It rejects HTML error and login pages.
  • Local images must be regular files, not directories, FIFOs, or device files.
  • At most 1 MiB per image.
  • Raster images may be at most 4096 pixels on each side.
  • SVG files must be well formed. Devsy rejects DTDs, entities, scripts, foreignObject, embedded documents, and external references. Shapes, paths, gradients, and references to elements in the same file are allowed.
  • Each download gets five seconds and at most five redirects. Devsy sends credentials only to the origin that issued them.

Icons are optional

A missing, invalid, or unreachable image never blocks installing or updating a provider. Devsy records that variant as missing and the Desktop app falls back. Devsy logs at most one short warning per failed asset revision, without the query string or credentials.

If an update cannot fetch the new icon, the Desktop app stops showing the previous logo for that variant. Run devsy provider set-source <name> later to fetch it again.

Providers installed before icon caching have no cached icon until you update them or run devsy provider set-source <name>.

Fallback order

The Desktop app uses the first image that loads:

App themeOrder
LightProvider icon, bundled logo for a known provider name, generic placeholder
DarkProvider iconDark, provider icon, bundled logo, placeholder

"App theme" is the theme the app shows: the system setting when the app theme is System, otherwise the chosen theme. A provider image wins over a bundled logo, even when the provider name matches a built-in name such as docker. If an image fails to load, the app moves to the next entry without retrying.

Test icons across versions

Use a provider repository with two tags and different logos to test the full path.

  1. Create a repository with provider.yaml that sets icon: assets/logo.svg. Commit a red logo as assets/logo.svg and tag it v0.0.1. Publish a release for that tag with provider.yaml attached.

  2. Replace assets/logo.svg with a blue logo, change version to v0.0.2, commit, tag v0.0.2 and publish that release.

  3. Install version A and note the red logo in the Desktop app:

    devsy provider add github.com/<owner>/<repo>@v0.0.1
  4. Update to version B. The logo turns blue:

    devsy provider set-source <name> --version v0.0.2
  5. Revert to version A. The logo turns red again:

    devsy provider set-source <name> --version v0.0.1

Each step shows the logo for the selected tag, never a mix of one version's provider with the other version's image.

On this page