Skip to main content

Official Plugins

Official plugins are native Atmos packages maintained by Cloud Posse. Each package has its own version and release lifecycle, so plugin updates are independent of Atmos releases.

Experimental

Use the built-in cloudposse registry to discover published releases:

atmos plugin search --registry=cloudposse --refresh

This directory describes the maintained packages. A package's source manifest does not establish that a release has been published; registry discovery reports available releases. See the Plugins overview for installation, configuration, development, and policy guides.

Secret-store authentication​

The cloudposse/auth-secrets package reads declared Atmos secret references and maps selected values into the environment of a command. Use it when a tool needs an API token or another secret from an Atmos store.

It exports two capabilities in one package:

KindCapabilityPurpose
secrets/storeAuthentication providerRead the secret references declared in the provider's configuration.
secrets/envCredential-exchange identityMap selected provider fields to named environment variables for a command.

Only explicitly mapped fields enter the command's environment. The secret store must be marked secret, and referenced values must be text. For example, a provider can read a service token from AWS Systems Manager Parameter Store and an identity can expose it as SERVICE_TOKEN.

Install​

OCI source:

oci://ghcr.io/cloudposse/atmos/plugins/auth-secrets

From your Atmos project, install an available release:

atmos plugin install oci://ghcr.io/cloudposse/atmos/plugins/auth-secrets --as=secrets

Commit the resulting package declaration in atmos.yaml and .atmos.plugins.lock.yaml. The lockfile records the selected release; you do not need Go to install the compiled package.

Configure and use​

Follow the complete configuration example to configure a secret store, a secrets/store provider, and a secrets/env identity. Select that identity when running an Atmos command that supports identities.

See the package README for credential validation and lifecycle details, or the official release guide for maintainer instructions.

SSH key identities​

The cloudposse/ssh package makes an SSH key an Atmos identity. Git signing, SSH logins, and private Git fetches then use a key that Atmos knows by name. On a Mac the private key is generated in the Secure Enclave and cannot be exported. On other platforms it is an ordinary key file.

It exports three capabilities in one package:

KindCapabilityPurpose
ssh/selfAuthentication providerSupply no upstream credential. Use it when nobody vouches for the key, or when you add the public key yourself.
ssh/keyCredential-exchange identityCreate the key, enroll it with an authority, and point tools at it.
sshCommandInspect and manage keys and the agent that serves them.

A key unattended work can use is the main reason to choose this package. By default the key works while the screen is locked, so a coding agent or a scheduled job can sign commits and reach hosts. Add require: unlocked and the Secure Enclave refuses the key while the screen is locked.

Install​

OCI source:

oci://ghcr.io/cloudposse/atmos/plugins/ssh
atmos plugin install oci://ghcr.io/cloudposse/atmos/plugins/ssh --as=ssh

Configure​

This example enrolls the key on a GitHub account. The token comes from a secret store through the secrets/store provider of the auth-secrets package.

plugins:
packages:
ssh:
source: oci://ghcr.io/cloudposse/atmos/plugins/ssh
version: "^0.1.0"
secrets:
source: oci://ghcr.io/cloudposse/atmos/plugins/auth-secrets
version: "^1.1.0"
aliases:
ssh: plugin run ssh --
stores:
keychain:
type: keychain
secret: true
auth:
providers:
github-token:
kind: secrets/store
spec:
credentials:
token: {store: keychain, path: github/ssh-keys}
identities:
ops:
kind: ssh/key
via: {provider: github-token}
spec:
authority: github
store: secure-enclave
allow: [signing, authentication]
require: unlocked
user: deploy
git:
repositories:
infra:
auth: {identity: ops}
commit: {signing: always}

Without a token, use the ssh/self provider and authority: self, then give the public key to whoever needs it. atmos ssh key show <name> --format github prints the form GitHub expects.

auth:
providers:
local:
kind: ssh/self
identities:
ops:
kind: ssh/key
via: {provider: local}
spec:
store: secure-enclave
allow: [signing]

Create the key and enroll it once per machine with atmos auth login:

atmos auth login --identity ops
atmos auth exec --identity ops -- git commit -m "signed with the enclave key"

The configuration is shared across a team, but each person's login creates and enrolls that machine's own key. Login is idempotent: when nothing has changed it makes no network call.

Identity fields​

Set these under spec of an ssh/key identity.

authority
Who vouches for the key: self (default) or github. With github, the upstream credential's token entry is used to enroll the key on the account the token belongs to.
store
Required. secure-enclave holds the key in macOS hardware. file is an ordinary key file that works on every platform and is not hardware-protected.
allow
Required. signing, authentication, or both. It limits the identity's agent socket to Git signing, SSH logins, or both, and it decides what is enrolled.
require
One term or a list. The only term is unlocked: the key is refused while the screen is locked. The key store enforces it and it is fixed when the key is created. The file store cannot enforce it and rejects it.
user
The SSH login name on the remote side. Exported as ANSIBLE_REMOTE_USER when authentication is allowed.
key
The key's name in the store. Defaults to the identity's name. Identities that share a key must agree on store and require.
rewrite_https
Hosts whose HTTPS Git URLs are rewritten to SSH.
root
The plugin's data directory, when it is not the default. The plugin cannot see Atmos's environment, so a relocated Atmos data directory must be named here and in the command's config.

What the identity sets​

SSH_AUTH_SOCK
Always. The identity's own agent socket.
GIT_CONFIG_GLOBAL
When signing is allowed or rewrite_https is set. A generated file that includes your own Git configuration first, then enables SSH signing with the identity's key and applies the URL rewrites.
ANSIBLE_REMOTE_USER
When user is set and authentication is allowed.

Commands​

Run atmos plugin run ssh -- <arguments>, or atmos ssh <arguments> with the alias shown above.

key list
key show <name> [--format authorized-key|allowed-signers|github|json]
key status [<name>]
key delete <name> --yes
agent start | stop | status | log [--lines N]
test <identity> [--soak <duration>] [--interval <duration>]
key list, key show
List the keys on this machine, or print one key's public half in the format a service expects.
key status
Show what this machine has enrolled, when the enrollment expires, and the last login result and error. Atmos does not show plugin text during login, so this is where to read why a login failed.
key delete
Delete the local key. The authority is updated at the next atmos auth login or atmos auth logout. Requires --yes.
agent start, stop, status, log
Control the per-user agent that serves the identities' sockets and read its audit log.
test
Sign a Git payload through the identity's socket and verify it. With --soak it repeats every --interval and prints one line per attempt (ok, refused, locked, or unreachable). It exits non-zero if any attempt failed. Run it, then lock the screen, to check what require does.

Commands never contact an authority and never prompt. Changes at an authority go through atmos auth login and atmos auth logout. Use --root <dir> when the data directory is not the default, and --store <kind> to pick a store when a key name exists in more than one.

GitHub enrollment​

With authority: github, login adds the public key to the account the token belongs to: as a signing key when signing is allowed, and as an authentication key when authentication is allowed. The token needs write:ssh_signing_key for signing, plus write:public_key for authentication. Grant it no other scopes.

The identity keeps a copy of the token in its private state so that logout can revoke the enrollment, and the host removes that copy at logout. An enrollment is revoked once its key is gone, so logging out alone never strips the key from a machine that still uses it. To retire a machine, run atmos ssh key delete ops --yes, then atmos auth logout ops.

Security model​

  • The key cannot leave the machine. A stolen disk, backup, or copied key blob is useless elsewhere. After a reboot nothing signs until the first login.
  • A per-user daemon (a LaunchAgent on macOS, a systemd user unit on Linux) serves the sockets. It rejects connections from other users, and each identity's socket signs only what allow permits.
  • require: unlocked is enforced by the key store, so it holds even against other processes running as you.
  • Any other process running as the same user can read the key file and use it directly, bypassing the allow limits. Do not mount the key directory into a sandbox.

Current limits​

  • There is no GitHub device login yet. Enrollment needs a token from a secret store, or you add the public key yourself with authority: self.
  • Atmos does not show plugin error text during login, so a failed login is a generic failure. Read the reason with atmos ssh key status.
  • Hardware-backed keys exist on macOS only. The file store works everywhere and is not hardware-protected.
  • The daemon does not run on Windows yet. An ssh/key identity fails there with a "not supported" error.
  • Atmos components do not all receive an identity's environment yet; Ansible needs a core change.

See the package README and the plugin configuration reference for more.