Plugins

Declare the native plugins a project uses, where to discover them, and which releases Atmos may install. Declarations and the release lock are committed with the project, so every machine and CI run restores the same reviewed release.

Experimental

Usage

atmos.yaml

plugins:
  max_concurrency: 4
  packages:
    corporate:
      source: oci://registry.example.com/team/oidc
      version: "^0.1.0"
      timeout: 5m
  registries:
    team:
      host: registry.example.com
      identity: registry-reader
      repositories:
        - oci://registry.example.com/team/oidc
  discovery:
    cache_ttl: 15m
  policy:
    require_signature: true
    trusted_publishers:
      - publisher: acme
        identity: "https://github.com/acme/atmos-oidc/.github/workflows/release.yaml@refs/tags/*"
        issuer: "https://token.actions.githubusercontent.com"

Manage the declarations with atmos plugin install, update, remove, and registry add. These commands edit only the keys they own and keep your comments and formatting. The selected release is recorded in .atmos.plugins.lock.yaml, next to atmos.yaml.

plugins

max_concurrency: Maximum parallel downloads and discovery requests. Defaults to 4; 1 installs sequentially. Negative values are invalid.
cache_dir: Storage root for downloaded releases and discovery metadata. Defaults to the Atmos XDG data and cache directories.

plugins.packages.<alias>

source: OCI repository of the release, such as oci://registry.example.com/team/oidc. Required while the package is enabled, unless path is set.
version: Semantic version constraint. Required while the package is enabled, unless path is set. plugin install records ^1.4.2 (or ^0.1.0 for a 0.x release, and an exact version for a pre-release) when you install a new package without --version.
path: Directory of a locally built plugin: the folder that holds plugin.yaml and the executable it names. A relative path is relative to the project directory (the directory of the root atmos.yaml); an absolute path is used as is. When set, it wins over source and version, which stay valid and apply again when path is not set. Atmos reads the manifest and the executable from the directory on every activation, so rebuilding is enough; the package has no lock entry, is not cached, and is not checked for a signature or version. Set it in a profile of your own so the local build applies only while that profile is active. plugin install skips the package, install --frozen refuses while it is set, and plugin list reports state path. Atmos prints one warning per alias when it starts the plugin.
enabled: false keeps the declaration but skips installation and activation, including a configured path. Source and version are not required while disabled.
timeout: Positive Go duration, such as 30s or 5m, that bounds every call into the plugin. Omit for no deadline.
command: Command export that plugin run starts when the package exports several.
config: Settings passed to the plugin command, validated against the command's schema when it declares one.
scope: Only project is supported.

Packages install automatically only when a command needs one of their exports, and CI refuses to create a lock entry that is not already committed. See automatic installation.

Atmos includes the cloudposse registry with catalog oci://ghcr.io/cloudposse/atmos/plugins/catalog:stable. An explicit registries.cloudposse replaces that entire entry. Removing it with atmos plugin registry remove cloudposse disables the implicit default as well.

plugins.registries.<name>

host: Registry authority used for authentication, independent of discovery. Inferred from catalog or repositories when omitted. All sources must share one host.
identity: Name of an auth.identities entry that authenticates to the host. An identity binding is exclusive: a failure does not fall back to Docker or ambient credentials.
auth: Only docker (the shared Docker and stored-credential chain) is supported. registry add writes it when no identity is set.
catalog: Optional OCI reference to a curated discovery catalog.
repositories: OCI repositories that Atmos indexes directly, without a catalog.

The order Atmos uses to pick credentials is in credential precedence.

plugins.discovery

default_registry: Include the built-in Cloud Posse catalog. Defaults to true. Set false for private-only discovery. Explicit registry entries remain active, including an explicit cloudposse override. Direct OCI installation does not need discovery.
cache_ttl: How long discovery metadata stays fresh, as a nonnegative Go duration. Defaults to 15m; 0 revalidates on every online search.

plugins.policy

require_signature: Admit only releases signed by a trusted publisher. It governs released packages; a package that sets path has no signature and is governed by plugin policy rules over origin: development and input.path. Needs at least one entry in trusted_publishers in some loaded configuration file. Later files cannot turn it off.
trusted_publishers: List of publisher (the namespace before / in the package name), identity (the signer's certificate subject; * is the only wildcard), and issuer (exact). A non-empty list enables enforcement.
offline: Forbid registry access. Installation, restoration, and corrupt-cache repair then need an explicit --from-layout, and discovery serves the cache even when stale.

For signature setup and offline verification, see trusted publishers. To restrict registries, package names, and local builds for the whole organization, use plugin policies. For the development loop that path enables, see the plugin development tutorial.

Official secret-store authentication

The cloudposse/auth-secrets plugin exports secrets/store, a provider that reads declared Atmos secret references, and secrets/env, an identity that maps selected values into a command's environment.

atmos.yaml

plugins:
  packages:
    secrets:
      source: oci://ghcr.io/cloudposse/atmos/plugins/auth-secrets
      version: 1.0.0

stores:
  team:
    type: aws-ssm-parameter-store
    secret: true
    options:
      region: us-east-1

auth:
  providers:
    service-secrets:
      kind: secrets/store
      spec:
        credentials:
          token:
            store: team
            key: /services/example/token
  identities:
    service:
      kind: secrets/env
      via:
        provider: service-secrets
      principal:
        environment:
          SERVICE_TOKEN: token

Install with atmos plugin install, commit the plugin lockfile, and select the service identity when running a command. Only the mapped fields enter the command environment. Values are masked, bounded to 1 MiB, and must be text without NUL bytes. Environment names must use letters, digits, and underscores, start with a letter or underscore, and be unique ignoring case.

Each reference requires store and key; optionally supply both stack and component for a scoped lookup. The store must be secret-enabled. Its explicit store identity is respected; otherwise the backend uses ambient credentials. Circular dependencies between the provider and a store's identity fail before reading secrets.

Authentication rereads the stores. Five-minute credentials allow reuse within the current process; a fresh process reads them again. Logout clears the identity's environment. Atmos does not change its own process environment or write cloud credential files for this identity. The native plugin runs as your operating-system user and must still be trusted.

The package version is independent of the Atmos version. Releases contain all six supported platforms in an OCI index; installation downloads only your platform's executable payload. See the official package release guide for publication and public GHCR setup.

Usage​

plugins​

plugins.packages.<alias>​

plugins.registries.<name>​

plugins.discovery​

plugins.policy​

Official secret-store authentication​