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  # URL or local path
      checksum: <sha256 of the file>
      name: my-binary             # optional, defaults to the file name
    - 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.

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  # executable inside the archive
      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 SHA256 of the file it runs and compares it case-insensitively. For an HTTP(S) archive, that file is the one extracted at archivePath, never the archive. A mismatch deletes the file and fails the download without retrying.

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