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:
  MY_OPTION:
    description: "this is my option"
    default: "default_value"
    required: false
    password: true

Devsy validates options when the provider is added. It passes them to every command as environment variables. Options can also appear in the agent section and in agent.exec. The provider reads and validates its own variables. Put that check in the init command, which Devsy runs 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.
  • 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:

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:

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

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