Skip to main content

Quickstart Guide

On this page we will cover all the basics to develop a functional provider for DevPod.

Recommended Reading

Before starting, it's best if you have already taken a look at What are providers and How to manage them.

Provider Examples

Another good starting point are the official DevPod providers specified at Add Provider

A very basic provider that reuses local Docker to spin up workspaces would look like this:

name: my-first-provider  # Required name of the provider
version: v0.0.1 # Required version of the provider
agent: # DevPod Agent options
path: ${DEVPOD} # Path to the current DevPod binary
# Command specifies how to run a command in the environment.
# In this case we want to reuse the local environment, so we just execute the command in a local shell.
command: |-
sh -c "${COMMAND}"

You can save this provider to a file called provider.yaml and then add it via:

devpod provider add ./path/to/provider.yaml

Then try to start a new workspace with:

devpod up

Developing a DevPod provider

DevPod providers are small CLI programs defined through a provider.yaml that DevPod interacts with, in order to bring up the workspace.

Providers are standalone programs that DevPod will call, parsing a manifest called provider.yaml that will instruct DevPod on how to interact with the program. The most important sections of a provider.yaml are:

  • exec: Defines what commands DevPod should execute to interact with the environment
  • options: Defines what Options the user can configure in the provider
  • binaries: Defines what additional helper binaries are required to run the provider
  • agent: Defines configuration options for the provider such as drivers, auto-inactivity timeout and credentials injection


With the provider.yaml, DevPod will know how to call the provider's binary, in order to perform all the required actions to bring up or down an environment for a workspace.

Following is a minimal example manifest for a provider:

name:  name-of-provider
version: version-number
description: quick description # Optional
icon: # Shown in the Desktop App
# Options for the provider, DevPod will pass these as
# ENV Variables when calling the provider
description: "option description"
default: "value"
required: true # or false
description: The path where to inject the DevPod agent to.
default: /opt/devpod/agent
path: ${AGENT_PATH}
command: # Required: a command to execute on the remote machine or container
init: # Optional: a command to init the provider, login to an account or similar
create: # Optional: a command to create the machine
delete: # Optional: a command to delete the machine
start: # Optional: a command to start the machine
stop: # Optional: a command to stop the machine
status: # Optional: a command to get the machine's status
binaries: # Optional binaries DevPod should download for this provider
MY_BINARY: # Will be available as MY_BINARY environment variable in the exec section

How DevPod interacts with a provider

DevPod uses the exec section within the provider.yaml to know what commands it needs to execute to interact with the provider environments. These "commands" are regular POSIX shell scripts that call a helper program or directly interact with the underlying system of the user to manage the environment.

In the exec section of the provider.yaml, the following commands are allowed:

  • command: The only command that is required for a provider to work, which defines how to run a command in the environment. DevPod will use this command to inject itself into the environment and route all communication through the commands standard output and input. An example for a local development provider would be: sh -c "${COMMAND}".
  • init: Optional command to check if options are defined correctly and the provider is ready to create environments. For example for the Docker provider, this command checks if Docker is installed and reachable locally.
  • create: Optional command how to create a machine. If this command is defined, the provider will automatically be treated as a machine provider and DevPod will also expect delete to be defined.
  • delete: Optional command how to delete a machine. Counter command to create.
  • start: Optional command how to start a stopped machine. Only usable for machine providers.
  • stop: Optional command how to stop a machine. Only usable for machine providers.
  • status: Optional command how to retrieve the status of a machine. Expects one of the following statuses on standard output:
    • Running: Machine is running and ready
    • Busy: Machine is doing something and DevPod should wait (e.g. terminating, starting, stopping etc.)
    • Stopped: Machine is currently stopped
    • NotFound: Machine is not found
Windows Compatibility

DevPod will execute these commands on Unix systems directly in a POSIX shell, while on Windows in an emulated shell to provide compatibility. However, not all commands, such as grep, sed etc. are available there and if needed, such functionality should be transferred to a small helper binary DevPod can download and install through the binaries section.

For example, taking the SSH Provider:

init: |-
OUTPUT=$(ssh -oStrictHostKeyChecking=no \
-p ${PORT} \
"${HOST}" \
'sh -c "echo DevPodTest"')

if [ "$OUTPUT" != "DevPodTest" ]; then
>&2 echo "Unexpected ssh output."
>&2 echo "Please make sure you have configured the correct SSH host"
>&2 echo "and the following command can be executed on your system:"
>&2 echo ssh -oStrictHostKeyChecking=no -p "${PORT}" "${HOST}" 'sh -c "echo DevPodTest"'
exit 1

command: |-
ssh -oStrictHostKeyChecking=no \
-p ${PORT} \
"${HOST}" \

The init is used to perform actions in order to verify and validate the options passed (in this case try a dummy command on the selected host)

The command is used to access the remote environment. ${COMMAND} will be supplied by DevPod and is a placeholder for the command DevPod will execute. In case of Machines providers this will usually have to SSH on the VMs created.

Non-Machine provider

For Non-Machine providers that don't want to manage any machine lifecycle, the available commands that can be used are:

  • command
  • init (optional)

Machine provider

For Machine Providers, you can use all of the commands in order to guarantee a full VMs lifecycle management.


The Options section is a set of OPTION_NAME and values that DevPod will inject in the environment when calling the provider's commands.

Head over to the Options Page to know more about how to set them up


One important part of the lifecycle management of the DevPod's provider's resources is the Agent. The agent is a helper that DevPod will inject into the workspace in order to perform utilities like:

  • auto-shutdown the VM after inactivity
  • inject git credentials
  • inject docker credentials

Head over to the Agent page to know more about the agent setup.


DevPod allows you to install additional binaries that help you to create cloud resources or access these. For example, the Google Cloud provider installs its own binary via:

- os: linux
arch: amd64
checksum: 38f92457507563ee56ea40a2ec40196d12ac2bbd50a924d76f55827e96e5f831
- os: linux
arch: arm64
checksum: 48e8dfa20962f1c3eb1e3da17d57842a0e26155df2b94377bcdf5b8070d7b17e
- os: darwin
arch: amd64
checksum: 43ee6ecb7855d282a0512ccf6055cce029895f173beb95a8c442f77560d26678
- os: darwin
arch: arm64
checksum: c2c2d57c5d48f22814f2393f61fd6a78bdc2cde7eabc3faffd8f35eaceec4422
- os: windows
arch: amd64
checksum: 9b81ec48c849f222aaf30f0cb85057d4e6619d1c0f787b27925c8b8adb431a58
init: ${GCLOUD_PROVIDER} init
command: ${GCLOUD_PROVIDER} command
create: ${GCLOUD_PROVIDER} create
delete: ${GCLOUD_PROVIDER} delete
start: ${GCLOUD_PROVIDER} start
stop: ${GCLOUD_PROVIDER} stop
status: ${GCLOUD_PROVIDER} status

You can find more information on the Provider binaries page.