Devsy
Developing Providers

Provider Binaries

The binaries section lists helper binaries Devsy downloads for a provider, such as a cloud CLI.

Each entry has a name and one item per platform:

binaries:
  MY_BINARY:
    - os: linux
      arch: amd64
      path: https://example.com/my-binary-linux-amd64
      checksum: <sha256 of the file>
      name: my-binary
    - os: darwin
      arch: arm64
      path: https://example.com/my-binary-darwin-arm64
      checksum: <sha256 of the file>

Supported archives are .tgz, .tar, .tar.gz and .zip. When a user adds the provider, Devsy downloads the item that matches their OS and architecture and verifies checksum if set.

path can also point to a local executable. name sets the installed file name for a direct download and defaults to the file name in path.

See the official providers, such as devsy-provider-aws, for complete examples.

Not every provider needs binaries. Built-in providers that wrap a CLI the user already has, such as docker, expose an option like DOCKER_PATH instead of downloading one.

Archives

Devsy extracts archives only when path is an http:// or https:// URL, and picks the format from the path extension, not from archivePath. archivePath is required when path is an archive. On a direct binary URL, archivePath makes Devsy try to extract the binary and fail with unrecognized archive format.

binaries:
  MY_BINARY:
    - os: linux
      arch: amd64
      path: https://example.com/my-binary-linux-amd64.tar.gz
      archivePath: bin/my-binary
      checksum: <sha256 of bin/my-binary after extraction>

Devsy extracts the whole archive into a folder for the binary and keeps its layout, then runs the file at archivePath. Devsy ignores name for HTTP(S) archives.

Checksum

checksum is optional, except for the agent.binaries entry selected by agent.external.binary, which needs one for every platform. See External Driver.

When set, Devsy computes the SHA-256 of the executable and compares it case-insensitively. For an HTTP(S) archive, it checks the extracted file at archivePath, not the archive. A downloaded file with a checksum mismatch is removed, and the download fails without retrying. A local source file with a mismatch is left in place. Verify the binary against a trusted source before changing its checksum. Update the manifest checksum only for an intentional, verified binary change; otherwise, restore the expected file before trying again.

Use a binary

Devsy exposes each binary's path as an environment variable with the same name.

In exec:

exec:
  init: ${MY_BINARY} init

In an option command:

options:
  MY_OPTION:
    command: ${MY_BINARY} retrieve-option

On the agent side, declare the binary under agent.binaries and use it in agent.exec:

agent:
  binaries:
    MY_BINARY:
      - os: linux
        arch: amd64
        path: https://example.com/my-binary-linux-amd64
        checksum: <sha256 of the file>
  exec:
    shutdown: ${MY_BINARY} stop

On this page