Skip to main content

Keyring

Atmos supports three keyring backends for storing authentication credentials. Configure the keyring in the auth.keyring section of your atmos.yaml.

System Keyring (Default)​

Uses your operating system's native secure credential storage:

  • macOS: Keychain
  • Linux: Secret Service (GNOME Keyring, KDE Wallet)
  • Windows: Windows Credential Manager

atmos.yaml

auth:
  keyring:
    type: system

This is the default and recommended option for interactive use. Credentials are stored securely using the operating system's built-in credential management.

File Keyring​

AES-256 encrypted file-based storage with password protection.

atmos.yaml

auth:
  keyring:
    type: file
    spec:
      path: ~/.atmos/keyring              # Optional custom path
      password_env: ATMOS_KEYRING_PASSWORD # Optional env var name
type
Required. Must be file.
spec.path
Optional. Custom path for the keyring file. Defaults to XDG data directory.
spec.password_env
Optional. Environment variable name containing the keyring password. Defaults to ATMOS_KEYRING_PASSWORD.

Password resolution order:

  1. Environment variable (ATMOS_KEYRING_PASSWORD or custom from password_env)
  2. Interactive prompt (if TTY available)
  3. Error if neither available

Use Cases​

File keyring is useful for:

  • Headless servers without system keyring support
  • Docker containers
  • CI/CD environments with persistent storage
  • Shared credentials across multiple machines

Memory Keyring​

In-memory storage with no persistence (credentials lost on exit).

atmos.yaml

auth:
  keyring:
    type: memory

Best for:

  • Unit tests
  • Temporary credential caching
  • Environments where persistence is not desired
warning

Memory keyring does not persist credentials. You will need to re-authenticate after every Atmos restart.

Environment Variables​

ATMOS_KEYRING_TYPE
Override keyring type (system, file, memory).
ATMOS_KEYRING_PASSWORD
Password for file keyring.

Choosing a Keyring Type​

TypePersistenceSecurityUse Case
systemYesHigh (OS-managed)Interactive workstations
fileYesMedium (encrypted)Servers, containers, CI/CD
memoryNoLow (in-process)Testing, temporary sessions

Storing Credentials​

Use atmos auth user configure to store IAM user credentials in the keyring:

# Store credentials for an aws/user identity
atmos auth user configure --identity emergency-user

This command prompts for access key ID and secret access key, then stores them securely in the configured keyring backend.

See Also​

  • Profiles — Use profiles to configure different keyring settings for CI vs local development