# 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

**File:** `atmos.yaml`

```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`](/cli/commands/plugin/install),
[`update`](/cli/commands/plugin/update), [`remove`](/cli/commands/plugin/remove), and
[`registry add`](/cli/commands/plugin/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](/cli/commands/plugin/usage#automatic-installation).

## 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](/cli/commands/plugin/registry-login#credential-precedence).

## plugins.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](/cli/commands/plugin/usage#require-trusted-publishers).
To restrict registries, package names, and local builds for the whole organization, use [plugin policies](/policies/plugins).
For the development loop that `path` enables, see the [plugin development tutorial](/tutorials/plugin-development).