Quickstart Guide

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

A minimal providerCopy Anchor Link

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.yamlCopy Anchor Link

• name, version: required. description and icon are 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, including the driver, inactivity timeout and credentials.

execCopy Anchor Link

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. ${COMMAND} is a placeholder Devsy fills in.
• 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, and delete is then 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, where tools such as grep and sed are not available. 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}"