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 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
~/.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
"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 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 doctor
Scan all agents in a project and prompt for any missing credentials:
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
mkdir -p ~/.action-llama/credentials/github_webhook_secret/MyOrg
echo "your-webhook-secret" > ~/.action-llama/credentials/github_webhook_secret/MyOrg/secret
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
repo, read:org, workflow).
Credential not found at runtime
Agents only receive credentials listed in their config.toml:
credentials = ["github_token", "git_ssh"]