Devsy
Developing Providers

Provider Options

Options are settings the user configures for a provider, such as an account, region, VM size, or image. Define them in provider.yaml:

options:
  API_TOKEN:
    description: API token for the provider service
    required: true
    password: true

Devsy validates the option definitions when the provider is added. It resolves their values and passes them to provider commands as environment variables. The agent section can also reference these values. Use init for checks that need to contact the service, such as verifying a token. Devsy runs init when options change.

Attributes

  • displayName: name shown in tools such as the Desktop app, instead of the option name.
  • description: shown by devsy provider get and in the Desktop app.
  • default: default value, as a string. It can reference other options, for example ${OTHER}-suffix. Devsy resolves them in order. Cannot be combined with command.
  • required: the value must be non-empty. The CLI prompts for it, and the Desktop app asks for it.
  • password: treat the value as a secret. devsy provider get hides it, and the Desktop app shows a password field.
  • type: string (default), multiline, duration, number or boolean. Devsy validates the value against it. number accepts integers, not decimals; duration accepts Go durations such as 30s or 10m.
  • enum: the only allowed values. Devsy rejects anything else.
  • suggestions: values offered as autocomplete in the Desktop app. Not enforced, and not shown in the CLI.
  • validationPattern: regex the value must match.
  • validationMessage: error shown when the pattern does not match. A generic message is used if empty.
  • command: command that fills the value. It can reference other options. On Windows it runs in an emulated shell.
  • subOptionsCommand: command that prints more options, in the same YAML shape, based on other option values.
  • local: fill the option separately for each machine or workspace.
  • global: reuse the option for every machine or workspace. Cannot be combined with cache or mutable.
  • cache: re-run command after this duration, for example 5m. Use it for expiring values, such as tokens. Requires command.
  • hidden: hide the option in the Desktop app and devsy provider get. Use it for internal values.
  • mutable: allow changing the value on an existing machine or workspace. Cannot be combined with global.

Examples

Pass a variable from the user's machine:

options:
  AWS_ACCESS_KEY_ID:
    description: The AWS access key ID
    command: printf "%s" "${AWS_ACCESS_KEY_ID:-}"

Run a helper binary and cache the result:

options:
  AWS_TOKEN:
    local: true
    hidden: true
    cache: 5m
    description: The AWS auth token to use
    command: ${AWS_PROVIDER} token

The second example assumes the provider declares a helper binary named AWS_PROVIDER with a token command.

Built-in options

Use these in default and command. Some work only in local options, because the machine or workspace does not exist yet when other options resolve.

  • DEVSY: absolute path to the Devsy binary. Also available on the agent side.
  • DEVSY_OS: linux, darwin or windows.
  • DEVSY_ARCH: amd64 or arm64.
  • MACHINE_ID, MACHINE_FOLDER, MACHINE_CONTEXT, MACHINE_PROVIDER: the machine's ID, local folder, Devsy context and provider. Machine providers only.
  • WORKSPACE_ID, WORKSPACE_FOLDER, WORKSPACE_CONTEXT, WORKSPACE_PROVIDER: the same for a workspace. Non-machine providers only.
  • PROVIDER_ID, PROVIDER_CONTEXT, PROVIDER_FOLDER: the provider's name, context and config folder. The folder can hold provider-wide data such as session tokens.

Option groups

Option groups organize options in the Desktop app. The CLI ignores them.

optionGroups:
  - name: "AWS options"
    options:
      - AWS_ACCESS_KEY_ID
      - AWS_INSTANCE_TYPE
    defaultVisible: true
  - name: "Agent options"
    options:
      - AGENT_PATH
      - INACTIVITY_TIMEOUT

Groups are collapsed unless defaultVisible is true.

If your provider exposes AGENT_PATH, Devsy treats its value as a literal path, not a shell command. Host-tunnel startup escapes the resolved path, including spaces, apostrophes, and shell metacharacters.

On this page