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: trueDevsy 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 bydevsy provider getand 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 withcommand.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 gethides it, and the Desktop app shows a password field.type:string(default),multiline,duration,numberorboolean. Devsy validates the value against it.numberaccepts integers, not decimals;durationaccepts Go durations such as30sor10m.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 moreoptions, 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 withcacheormutable.cache: re-runcommandafter this duration, for example5m. Use it for expiring values, such as tokens. Requirescommand.hidden: hide the option in the Desktop app anddevsy provider get. Use it for internal values.mutable: allow changing the value on an existing machine or workspace. Cannot be combined withglobal.
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} tokenThe 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,darwinorwindows. - DEVSY_ARCH:
amd64orarm64. - 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_TIMEOUTGroups 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.