> ## Documentation Index > Fetch the complete documentation index at: https://docs.actionllama.org/llms.txt > Use this file to discover all available pages before exploring further. # Credentials > Credential types, storage, resolution, and management Credentials are stored in `~/.action-llama/credentials///`. 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 1. **Configuration**: List credential types in your agent's `config.toml`: ```toml theme={null} credentials = ["github_token", "git_ssh"] ``` 2. **Storage**: Credential values live in `~/.action-llama/credentials///`. Each field is a plain text file. 3. **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///`. In [host-user mode](/reference/agent-config#runtime), they are staged to a temp directory (path set via `AL_CREDENTIALS_PATH`) and chowned to the agent user. 4. **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`. 5. **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): ```bash theme={null} 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: ```bash theme={null} al creds rm github_token # default instance al creds rm github_webhook_secret:myapp ``` ### `al creds ls` List all stored credentials grouped by type: ```bash theme={null} 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. ```bash theme={null} al creds types ``` ### `al doctor` Scan all agents in a project and prompt for any missing credentials: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} al creds add github_webhook_secret:MyOrg ``` Or manually: ```bash theme={null} 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" ```bash theme={null} 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`: ```toml theme={null} 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.