Credentials

Credentials are stored in ~/.action-llama/credentials/<type>/<instance>/<field>. Each credential type is a directory containing one file per field. Reference them in your agent’s config.toml by type name (e.g. "github_token") for the default instance, or use "type:instance" for a named instance (e.g. "git_ssh:botty").

Built-in Credentials

Agent runtime credentials

Type	Fields	Description	Runtime Injection
`github_token`	`token`	GitHub PAT with repo and workflow scopes	`GITHUB_TOKEN` and `GH_TOKEN` env vars
`anthropic_key`	`token`	Anthropic API key or OAuth token for Claude or pi harness runs	`ANTHROPIC_API_KEY` or `CLAUDE_CODE_AUTH_TOKEN` for Claude harness; otherwise read by the pi runtime
`openai_key`	`token`	OpenAI API key	(read by SDK)
`groq_key`	`token`	Groq API key	(read by SDK)
`google_key`	`token`	Google Gemini API key	(read by SDK)
`xai_key`	`token`	xAI API key	(read by SDK)
`mistral_key`	`token`	Mistral API key	(read by SDK)
`openrouter_key`	`token`	OpenRouter API key	(read by SDK)
`custom_key`	`token`	Custom provider API key	(read by SDK)
`sentry_token`	`token`	Sentry auth token for error monitoring	`SENTRY_AUTH_TOKEN` env var
`linear_token`	`token`	Linear personal API token	`LINEAR_API_TOKEN` env var
`linear_oauth`	`client_id`, `client_secret`, `access_token`, `refresh_token`	Linear OAuth2 credentials	`LINEAR_CLIENT_ID`, `LINEAR_CLIENT_SECRET`, `LINEAR_ACCESS_TOKEN`, `LINEAR_REFRESH_TOKEN` env vars
`bugsnag_token`	`token`	Bugsnag auth token	`BUGSNAG_AUTH_TOKEN` env var
`netlify_token`	`token`	Netlify Personal Access Token	`NETLIFY_AUTH_TOKEN` env var
`mintlify_token`	`token`	Mintlify API token	`MINTLIFY_API_TOKEN` env var
`slack_bot_token`	`token`	Slack bot user OAuth token	`SLACK_BOT_TOKEN` env var
`git_ssh`	`id_rsa`, `username`, `email`	SSH private key + git author identity	SSH key mounted as file; `GIT_AUTHOR_NAME`/`GIT_AUTHOR_EMAIL`/`GIT_COMMITTER_NAME`/`GIT_COMMITTER_EMAIL` set from `username`/`email`
`x_twitter_api`	`api_key`, `api_secret`, `bearer_token`, `access_token`, `access_token_secret`	X (Twitter) API credentials	`X_API_KEY`, `X_API_SECRET`, `X_BEARER_TOKEN`, `X_ACCESS_TOKEN`, `X_ACCESS_TOKEN_SECRET` env vars
`aws`	`access_key_id`, `secret_access_key`, `default_region`	AWS credentials	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION` env vars
`reddit_oauth`	`client_id`, `client_secret`, `username`, `password`, `user_agent`	Reddit OAuth2 credentials for script apps	`REDDIT_CLIENT_ID`, `REDDIT_CLIENT_SECRET`, `REDDIT_USERNAME`, `REDDIT_PASSWORD`, `REDDIT_USER_AGENT` env vars

Webhook secrets

Type	Fields	Description
`github_webhook_secret`	`secret`	Shared secret for GitHub webhook HMAC verification
`sentry_client_secret`	`secret`	Client secret for Sentry webhook verification
`linear_webhook_secret`	`secret`	Shared secret for Linear webhook verification
`mintlify_webhook_secret`	`secret`	Shared secret for Mintlify webhook verification
`discord_bot`	`application_id`, `public_key`, `bot_token`	Discord bot credentials for Ed25519 webhook verification and API access. Injected as `DISCORD_APPLICATION_ID`, `DISCORD_PUBLIC_KEY`, `DISCORD_BOT_TOKEN`.
`slack_signing_secret`	`secret`	Signing secret for Slack webhook verification

Infrastructure credentials

These are used by CLI commands (provisioning, deployment) and are not injected into agent containers.

Type	Fields	Description
`gateway_api_key`	`key`	API key for dashboard and CLI access to the gateway
`vultr_api_key`	`api_key`	Vultr API key for VPS provisioning
`hetzner_api_key`	`api_key`	Hetzner API key for VPS provisioning
`cloudflare_api_token`	`token`	Cloudflare API token for DNS and TLS setup during provisioning
`vps_ssh`	`id_rsa`	SSH private key for VPS access (generated or selected during provisioning)
`gcp_service_account`	`key_json`	GCP service account JSON key for Cloud Run Jobs runtime (requires `roles/run.admin`, `roles/secretmanager.admin`, `roles/artifactregistry.admin`)

How Credentials Work

Configuration: List credential types in your agent’s config.toml:
credentials = ["github_token", "git_ssh"]
Storage: Credential values live in ~/.action-llama/credentials/<type>/<instance>/<field>. Each field is a plain text file.
Injection: When an agent runs, the credentials it requires are made available at a credentials path and key values are injected as environment variables. In Docker mode, credentials are mounted at /credentials/<type>/<instance>/<field>. In host-user mode, they are staged to a temp directory (path set via AL_CREDENTIALS_PATH) and chowned to the agent user.
Git identity: The git_ssh credential includes username and email fields (prompted during al new/al doctor). These are injected as GIT_AUTHOR_NAME/GIT_AUTHOR_EMAIL and GIT_COMMITTER_NAME/GIT_COMMITTER_EMAIL env vars at runtime, so git commit works without requiring git config.
LLM credentials: The LLM credential (e.g. anthropic_key) does not need to be listed in the agent’s credentials array — it is loaded automatically based on the [models.*] config and mapped into the selected harness.

Named Instances

Each credential type supports named instances. For example, you could have webhook secrets for multiple GitHub orgs:

~/.action-llama/credentials/github_webhook_secret/MyOrg/secret
~/.action-llama/credentials/github_webhook_secret/OtherOrg/secret

Or multiple SSH keys:

~/.action-llama/credentials/git_ssh/default/id_rsa
~/.action-llama/credentials/git_ssh/default/username
~/.action-llama/credentials/git_ssh/botty/id_rsa
~/.action-llama/credentials/git_ssh/botty/username

By default, just reference "git_ssh" — this resolves to the default instance. To use a named instance, use colon syntax: "git_ssh:botty".

Managing Credentials

`al creds add`

Add or update a credential interactively. Runs validation for the credential type (e.g. API key format, GitHub API check):

al creds add github_token              # default instance
al creds add github_webhook_secret:myapp
al creds add git_ssh:prod

`al creds rm`

Remove a credential:

al creds rm github_token               # default instance
al creds rm github_webhook_secret:myapp

`al creds ls`

List all stored credentials grouped by type:

al creds ls

`al creds types`

Browse available credential types interactively. Shows all 26 built-in types with their fields, environment variables, and descriptions. Offers to add the selected credential immediately.

al creds types

`al doctor`

Scan all agents in a project and prompt for any missing credentials:

al doctor

During `al new`

The al new command prompts for the Anthropic credential during initial setup. Other credentials are configured per-agent by al doctor or al creds add.

Manually

Write credential files directly:

mkdir -p ~/.action-llama/credentials/github_token/default
echo "ghp_your_token_here" > ~/.action-llama/credentials/github_token/default/token

mkdir -p ~/.action-llama/credentials/anthropic_key/default
echo "sk-ant-api-your_key_here" > ~/.action-llama/credentials/anthropic_key/default/token

Anthropic Auth Methods

Three auth methods are supported:

api_key — Standard API key (sk-ant-api-...). Set authType = "api_key" in model config.
oauth_token — OAuth token (sk-ant-oat-...). Set authType = "oauth_token".
pi_auth — Use existing pi auth credentials (~/.pi/agent/auth.json). Set authType = "pi_auth". No credential file needed. This is only supported with the pi harness.

Webhook Secrets

Webhook secrets use named credential instances. For example, to set up a GitHub webhook secret for your org:

al creds add github_webhook_secret:MyOrg

Or manually:

mkdir -p ~/.action-llama/credentials/github_webhook_secret/MyOrg
echo "your-webhook-secret" > ~/.action-llama/credentials/github_webhook_secret/MyOrg/secret

The gateway automatically loads secrets from all credential instances (e.g. github_webhook_secret:MyOrg, sentry_client_secret:MyOrg) and uses them to verify incoming webhook payloads. No global configuration is needed.

VPS Credential Sync

When deploying to a VPS, credentials are transferred to the remote server via SSH. The remote layout mirrors the local one: ~/.action-llama/credentials/{type}/{instance}/{field}. No external secrets manager is needed — same trust model as SSH access.

Troubleshooting

”Bad credentials” or “401 Unauthorized”

al doctor    # Re-prompts for missing or invalid credentials
al creds ls       # Verify stored credentials

For GitHub tokens, ensure the token has the required scopes (repo, read:org, workflow).

Credential not found at runtime

Agents only receive credentials listed in their config.toml:

credentials = ["github_token", "git_ssh"]

If a credential is missing from this list, the agent won’t have access to it. Add it and re-run.

First Steps

Guides

Concepts

Integrations

Reference

Built-in Credentials

Agent runtime credentials

Webhook secrets

Infrastructure credentials

How Credentials Work

Named Instances

Managing Credentials

`al creds add`

`al creds rm`

`al creds ls`

`al creds types`

`al doctor`

During `al new`

Manually

Anthropic Auth Methods

Webhook Secrets

VPS Credential Sync

Troubleshooting

”Bad credentials” or “401 Unauthorized”

Credential not found at runtime

​Built-in Credentials

​Agent runtime credentials

​Webhook secrets

​Infrastructure credentials

​How Credentials Work

​Named Instances

​Managing Credentials

​al creds add

​al creds rm

​al creds ls

​al creds types

​al doctor

​During al new

​Manually

​Anthropic Auth Methods

​Webhook Secrets

​VPS Credential Sync

​Troubleshooting

​”Bad credentials” or “401 Unauthorized”

​Credential not found at runtime

Built-in Credentials

Agent runtime credentials

Webhook secrets

Infrastructure credentials

How Credentials Work

Named Instances

Managing Credentials

`al creds add`

`al creds rm`

`al creds ls`

`al creds types`

`al doctor`

During `al new`

Manually

Anthropic Auth Methods

Webhook Secrets

VPS Credential Sync

Troubleshooting

”Bad credentials” or “401 Unauthorized”

Credential not found at runtime