Devsy
Developing Providers

Quickstart Guide

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 on the local machine:

name: my-first-provider  # required
version: v0.0.1          # required
agent:
  path: ${DEVSY}         # path to the current Devsy binary
exec:
  # How to run a command in the environment. Here: a local shell.
  command: |-
    sh -c "${COMMAND}"

Save it as provider.yaml, add it, and start a workspace:

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

Sections of provider.yaml

  • name, version: required. 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

Each entry is a POSIX shell script. Only command is required.

  • 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. Defining create makes the provider a machine provider, so delete is expected too.
  • start, stop: start and stop a machine. Machine providers only.
  • status: prints one of Running, Busy (wait and check again), Stopped or NotFound.
  • describe: prints a text description of the machine.

A provider without create is a non-machine provider and uses only command and init.

On Windows, Devsy runs these scripts in an emulated shell. The emulated shell has no grep or sed. Move that logic into a helper binary.

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