Provider Options

Options are settings the user can configure 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 and passes them to every command as environment variables. They can also be used in the agent section and in agent.exec. The provider is responsible for reading and validating its own variables. Put that check in the init command, which Devsy runs when options change.

AttributesCopy Anchor Link

• displayName: name shown by 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 the right order.
• required: the value must be non-empty. Devsy prompts for it in the CLI, and the Desktop app asks for it.
• password: treat the value as a secret. It is hidden in devsy provider get and entered in a password field in the Desktop app.
• 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 values that expire, such as tokens.
• 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.

ExamplesCopy Anchor Link

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 optionsCopy Anchor Link

These can be used in default and command. Some exist only for local options, because the machine or workspace does not exist yet when others are resolved.

• 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 groupsCopy Anchor Link

Option groups organize options in the Desktop app. They have no effect in the CLI.

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.