| name | env-reference |
| description | Full environment variable reference for SAM. Use when adding, modifying, or documenting environment variables, configuring deployment, or working with Worker secrets. |
| user-invocable | false |
SAM Environment Variable Reference
GitHub Environment Secrets (GitHub Settings -> Environments -> production)
Uses GH_* prefix because GitHub Actions secret names cannot start with GITHUB_*.
| Type | Name | Required |
|---|
| Variable | BASE_DOMAIN | Yes |
| Variable | RESOURCE_PREFIX | No (default: sam) |
| Variable | PULUMI_STATE_BUCKET | No (default: sam-pulumi-state) |
| Variable | CF_CONTAINER_ENABLED | No (default: true; set false to force VM runtime) |
| Secret | CF_API_TOKEN | Yes (requires Account → SSL and Certificates → Edit for Origin CA) |
| Secret | CF_ACCOUNT_ID | Yes |
| Secret | CF_ZONE_ID | Yes |
| Secret | DEVCONTAINER_CACHE_CLOUDFLARE_API_TOKEN | No (falls back to CF_API_TOKEN) |
| Secret | DEVCONTAINER_CACHE_CLOUDFLARE_ACCOUNT_ID | No (falls back to CF_ACCOUNT_ID) |
| Secret | R2_ACCESS_KEY_ID | Yes |
| Secret | R2_SECRET_ACCESS_KEY | Yes |
| Secret | PULUMI_CONFIG_PASSPHRASE | Yes |
| Secret | GH_CLIENT_ID | Yes |
| Secret | GH_CLIENT_SECRET | Yes |
| Secret | GH_APP_ID | Yes |
| Secret | GH_APP_PRIVATE_KEY | Yes |
| Secret | GH_APP_SLUG | Yes |
| Secret | GH_WEBHOOK_SECRET | Yes when GitHub App webhooks are active |
| Secret | ENCRYPTION_KEY | No (auto-generated) |
| Secret | JWT_PRIVATE_KEY | No (auto-generated) |
| Secret | JWT_PUBLIC_KEY | No (auto-generated) |
| Secret | DEPLOY_SIGNING_PRIVATE_KEY | No (auto-generated; override only) |
| Secret | DEPLOY_SIGNING_PUBLIC_KEY | No (derived during deploy; override only) |
| Secret | TRIAL_CLAIM_TOKEN_SECRET | No (auto-generated) |
| Variable | ORIGIN_CA_CERT_VALIDITY_DAYS | No (default: 7) |
ORIGIN_CA_CERT and ORIGIN_CA_KEY are legacy rotation inputs for nodes provisioned before per-node Origin CA CSR signing. They are not required for new node provisioning.
GH* to GITHUB* Mapping (done by configure-secrets.sh)
GitHub Secret -> Cloudflare Worker Secret
GH_CLIENT_ID -> GITHUB_CLIENT_ID
GH_CLIENT_SECRET -> GITHUB_CLIENT_SECRET
GH_APP_ID -> GITHUB_APP_ID
GH_APP_PRIVATE_KEY -> GITHUB_APP_PRIVATE_KEY
GH_APP_SLUG -> GITHUB_APP_SLUG
GH_WEBHOOK_SECRET -> GITHUB_WEBHOOK_SECRET
Use GH_WEBHOOK_SECRET in GitHub Actions because secret names cannot start with GITHUB_. The Worker/runtime secret remains GITHUB_WEBHOOK_SECRET, and it must match the GitHub App webhook secret exactly.
API Worker Runtime Environment Variables
See apps/api/.env.example for the full list. Key variables:
Core
WRANGLER_PORT — Local dev port (default: 8787)BASE_DOMAIN — Set automatically by sync scriptsCF_CONTAINER_ENABLED — Enables Cloudflare Container instant-session runtime in generated deployment envs (default: true; set false to force VM runtime)CF_CONTAINER_SLEEP_AFTER — Container idle sleep duration for instant-session runtime (default: 10m)CF_CONTAINER_VM_AGENT_PORT — vm-agent standalone HTTP port inside the raw container (default: 8080)CF_CONTAINER_PORT_READY_TIMEOUT_MS — Max wait for vm-agent port readiness (default: 30000)- `$1
SESSION_SNAPSHOT_TTL_DAYS — Retention for hibernated session snapshots; deployment also provisions matching R2 prefix expiration (default: 7)SESSION_SNAPSHOT_TOTAL_BUDGET_BYTES — Maximum bytes accepted for one snapshot artifact (default: 104857600)SESSION_SNAPSHOT_ENTRY_THRESHOLD_BYTES — Per-file threshold before snapshot content is visibly skipped (default: 52428800)SESSION_SNAPSHOT_TRANSFER_IDLE_TIMEOUT_MS — Progress-idle timeout for snapshot upload/download (default: 30000)SESSION_SNAPSHOT_JSON_BODY_MAX_BYTES — Maximum snapshot coordination JSON body (default: 262144)SESSION_SNAPSHOT_R2_PREFIX — Private R2 object prefix for session snapshots (default: session-snapshots)
Devcontainer Cache
DEVCONTAINER_CACHE_ENABLED — Enables opportunistic devcontainer image cachingDEVCONTAINER_CACHE_REGISTRY_HOST — Managed registry host (default: registry.cloudflare.com)DEVCONTAINER_CACHE_REPOSITORY_PREFIX — Prefix for generated cache repository namesDEVCONTAINER_CACHE_CREDENTIAL_EXPIRATION_MINUTES — TTL for short-lived registry credentials minted by the API
Google OAuth and GCP
GOOGLE_LOGIN_CLIENT_ID, GOOGLE_LOGIN_CLIENT_SECRET — Optional Google user-login OAuth fallback. Runtime /setup or superadmin config takes precedence. Callback: /api/auth/callback/google.GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET — Optional, independent infrastructure OAuth fallback used only for keyless GCP/WIF setup. Runtime superadmin config takes precedence. Callbacks: /auth/google/callback and /api/deployment/gcp/callback.GCP_WIF_POOL_ID, GCP_WIF_PROVIDER_ID, GCP_SERVICE_ACCOUNT_ID — Default identifiers used by WIF setup.GCP_SERVICE_ACCOUNT_JSON_MAX_BYTES — Maximum UTF-8 service-account JSON upload/paste size (default: 65536).GCP_DEFAULT_ZONE — Default Compute zone (default: us-central1-a).GCP_IMAGE_FAMILY, GCP_IMAGE_PROJECT, GCP_DISK_SIZE_GB — Compute VM image and disk defaults.GCP_TOKEN_CACHE_TTL_SECONDS — Maximum short-lived access-token cache TTL (default: 3300; capped by the provider-returned expiry).GCP_IDENTITY_TOKEN_EXPIRY_SECONDS — WIF SAM identity-token lifetime (default: 600).GCP_OPERATION_POLL_TIMEOUT_MS — GCP asynchronous operation timeout (default: 300000).GCP_API_TIMEOUT_MS — Timeout for Google OAuth, IAM, and Compute verification requests (default: 30000).GCP_STS_SCOPE — WIF STS scope (default: https://www.googleapis.com/auth/cloud-platform).GCP_SA_IMPERSONATION_SCOPES — Comma-separated WIF service-account impersonation scopes (default: Compute).GCP_SA_TOKEN_LIFETIME_SECONDS — WIF impersonated-token lifetime (default: 3600).GCP_STS_TOKEN_URL, GCP_IAM_CREDENTIALS_BASE_URL — WIF endpoint overrides for controlled environments. They do not affect service-account JWT exchange, which always uses Google's fixed OAuth token endpoint.GCP_DEPLOY_WIF_POOL_ID, GCP_DEPLOY_WIF_PROVIDER_ID, GCP_DEPLOY_SERVICE_ACCOUNT_ID — Default identifiers for deployment WIF.GCP_DEPLOY_IDENTITY_TOKEN_EXPIRY_SECONDS, GCP_DEPLOY_OAUTH_STATE_TTL_SECONDS, GCP_DEPLOY_OAUTH_TOKEN_HANDLE_TTL_SECONDS — Deployment authorization lifetimes.
Resource Limits
MAX_NODES_PER_USER — Runtime node capMAX_AGENT_SESSIONS_PER_WORKSPACE — Runtime session capMAX_PROJECTS_PER_USER — Runtime project capMAX_TASKS_PER_PROJECT — Runtime task cap per projectMAX_TASK_DEPENDENCIES_PER_TASK — Runtime dependency-edge cap per taskPROJECT_INVITE_TOKEN_BYTES — Random bytes used for generated project invite link tokens (default: 32)PROJECT_INVITE_DEFAULT_EXPIRY_DAYS — Default lifetime for project invite links created without an explicit expiry (default: 7)PROJECT_INVITE_MAX_EXPIRY_DAYS — Maximum allowed project invite link lifetime (default: 30)AGENT_SETTINGS_VALIDATION_LIMITS — Optional JSON object overriding
agent-settings validation bounds for model IDs, tool lists, additional env
entries, provider display names, and OpenCode base URLs. See
apps/api/.env.example and apps/www/src/content/docs/docs/guides/self-hosting.md for supported keys
and defaults.
Pagination
TASK_LIST_DEFAULT_PAGE_SIZE — Default task/project list page sizeTASK_LIST_MAX_PAGE_SIZE — Maximum task/project list page sizeCHAT_SESSION_MESSAGE_LIMIT — Default page size for chat session message REST responses when no limit is requested — used by the 3s poll and load-more (default: 500)CHAT_SESSION_MESSAGE_MAX — Ceiling any chat session message request is clamped to; the initial full-conversation load requests up to this (default: 50000)
Timeouts
TASK_CALLBACK_TIMEOUT_MS — Timeout budget for delegated-task callback processingTASK_CALLBACK_RETRY_MAX_ATTEMPTS — Retry budget for delegated-task callback processingTASK_RECONCILIATION_IDLE_MS — Idle threshold before a visible task reconciliation check-in (default: 300000)TASK_RECONCILIATION_RESPONSE_DEADLINE_MS — Response deadline after a visible task reconciliation check-in (default: 60000)TASK_RECONCILIATION_PROMPT_SOFT_STALL_MS — In-flight prompt observation threshold before SAM records a non-interrupting reconciliation event (default: 1800000)TASK_RECONCILIATION_PROMPT_HARD_STALL_MS — In-flight prompt hard-stall threshold before SAM requests prompt cancellation and retries check-in later (default: 7200000)TASK_RECONCILIATION_MIN_ALARM_DELAY_MS — Minimum delay before the next reconciliation alarm can fire (default: 10000)SESSION_TASK_REPAIR_BATCH_SIZE — Maximum legacy taskless chat sessions repaired per 5-minute sweep (default: 25; capped at 200)TASK_RUN_ABSOLUTE_CEILING_MS — Absolute runaway-cost ceiling that fails even a demonstrably live task (default: 86400000 / 24h)SESSION_ACTIVITY_STALE_THRESHOLD_MS — Evidence-based fallback threshold before stale working activity can be healed to idle (default: 300000)NODE_HEARTBEAT_STALE_SECONDS — Staleness threshold for node healthNODE_AGENT_READY_TIMEOUT_MS — Max wait for freshly provisioned node-agent healthNODE_AGENT_READY_POLL_INTERVAL_MS — Polling interval for fresh-node readiness checksHETZNER_API_TIMEOUT_MS — Timeout for Hetzner Cloud API calls (default: 30000)CF_API_TIMEOUT_MS — Timeout for Cloudflare DNS API calls (default: 30000)NODE_AGENT_REQUEST_TIMEOUT_MS — Timeout for Node Agent HTTP requests (default: 30000)
Audio/Transcription
WHISPER_MODEL_ID — Workers AI model for transcription (default: @cf/openai/whisper-large-v3-turbo)MAX_AUDIO_SIZE_BYTES — Maximum audio upload size (default: 10485760)MAX_AUDIO_DURATION_SECONDS — Maximum recording duration (default: 60)RATE_LIMIT_TRANSCRIBE — Rate limit for transcription requests
Client Error Reporting
RATE_LIMIT_CLIENT_ERRORS — Rate limit per hour per IP (default: 200)MAX_CLIENT_ERROR_BATCH_SIZE — Max errors per request (default: 25)MAX_CLIENT_ERROR_BODY_BYTES — Max request body size (default: 65536)MAX_VM_AGENT_ERROR_BODY_BYTES — Max VM agent error request body (default: 32768)MAX_VM_AGENT_ERROR_BATCH_SIZE — Max VM agent errors per request (default: 10)
Project File Library
LIBRARY_LIST_DEFAULT_PAGE_SIZE — Default file-list page size (default: 50)LIBRARY_LIST_MAX_PAGE_SIZE — Maximum file-list page size (default: 200)LIBRARY_TAG_QUERY_BATCH_SIZE — File IDs per tag metadata lookup query (default: 80, capped below D1 bind-variable limits)- Other library upload, directory, search, preview, and encryption settings are listed in
apps/api/.env.example.
Codex OAuth Refresh Proxy (CodexRefreshLock DO + /api/auth/codex-refresh)
CODEX_REFRESH_PROXY_ENABLED — Kill switch; set to 'false' to disable the proxy entirely (default: enabled)CODEX_REFRESH_UPSTREAM_URL — OpenAI OAuth token endpoint (default: https://auth.openai.com/oauth/token)CODEX_REFRESH_UPSTREAM_TIMEOUT_MS — Timeout for upstream fetch (default: 10000)CODEX_REFRESH_LOCK_TIMEOUT_MS — Max DO lock hold time per refresh (default: 30000)CODEX_CLIENT_ID — Public OAuth client_id for Codex (default: app_EMoamEEZ73f0CkXaXp7hrann)CODEX_EXPECTED_SCOPES — Comma-separated allowlist of scopes the upstream may return. Unset uses the default allowlist (openid,profile,email,offline_access). Set to empty string ("") to disable validation entirely (escape hatch for provider-driven scope additions). Unexpected scopes block the refresh with 502; the previous token remains valid. (MEDIUM #6 fix)RATE_LIMIT_CODEX_REFRESH_PER_HOUR — Per-user refresh request cap per window (default: 30). Enforced atomically via DO storage, not KV. (MEDIUM #5 fix)RATE_LIMIT_CODEX_REFRESH_WINDOW_SECONDS — Rate-limit window length in seconds (default: 3600)
Credential Routes Rate Limits
RATE_LIMIT_CREDENTIAL_UPDATE — Credential mutation cap used by user/project agent-key writes and the atomic PUT /api/gcp/service-account and superadmin Google infrastructure OAuth rotation paths.
Generic Webhook Triggers
WEBHOOK_TRIGGERS_ENABLED — Public ingress kill switch (default: true)WEBHOOK_TRIGGER_MAX_BODY_BYTES — Maximum JSON request body (default: 65536)WEBHOOK_TRIGGER_MAX_FILTERS — Maximum deterministic filters per trigger (default: 10)WEBHOOK_TRIGGER_MAX_FILTER_PATH_LENGTH — Maximum filter dot-path length (default: 200)WEBHOOK_TRIGGER_MAX_FILTER_PATH_DEPTH — Maximum filter nesting depth at evaluation time (default: 8)WEBHOOK_TRIGGER_MAX_INCLUDED_HEADERS — Maximum safe request headers copied into template context (default: 10)WEBHOOK_TRIGGER_MAX_HEADER_NAME_LENGTH — Maximum configured included-header name length (default: 100)WEBHOOK_TRIGGER_MAX_SOURCE_LABEL_LENGTH — Maximum optional source label length (default: 100)WEBHOOK_TRIGGER_MAX_IDEMPOTENCY_KEY_LENGTH — Maximum Idempotency-Key length (default: 200)WEBHOOK_INGRESS_RATE_LIMIT_PER_MINUTE — Best-effort pre-auth request damping per IP/window (default: 120)WEBHOOK_TRIGGER_RATE_LIMIT_PER_MINUTE — Best-effort request damping per trigger/window (default: 60)WEBHOOK_INVALID_TOKEN_RATE_LIMIT_PER_MINUTE — Best-effort invalid-token request damping per IP/window (default: 30)WEBHOOK_RATE_LIMIT_WINDOW_SECONDS — Fixed rate-limit window length (default: 60)WEBHOOK_DELIVERY_RETENTION_DAYS — Retention for redacted delivery audit metadata (default: 7)WEBHOOK_DELIVERY_CLEANUP_BATCH_SIZE — Maximum expired audit rows deleted per cleanup pass (default: 500)WEBHOOK_DELIVERY_DEFAULT_PAGE_SIZE — Default delivery-history page size (default: 25)WEBHOOK_DELIVERY_MAX_PAGE_SIZE — Maximum delivery-history page size (default: 100)WEBHOOK_DELIVERY_PROCESSING_LEASE_SECONDS — Recovery lease for processing deliveries without a submitted task (default: 300)
Trial Onboarding (/try flow)
Trial configuration is currently sourced from apps/api/.env.example and apps/api/src/env.ts. Summary:
TRIAL_CLAIM_TOKEN_SECRET — Worker secret; HMAC key for trial cookies (auto-provisioned by Pulumi)TRIAL_MONTHLY_CAP, TRIAL_WORKSPACE_TTL_MS, TRIAL_DATA_RETENTION_HOURS — Global cap + lifetimesTRIAL_ANONYMOUS_USER_ID, TRIAL_ANONYMOUS_INSTALLATION_ID — Sentinel rows for pre-claim ownershipTRIAL_AGENT_TYPE_STAGING, TRIAL_AGENT_TYPE_PRODUCTION, TRIAL_DEFAULT_WORKSPACE_PROFILE — Agent + profile selectionTRIALS_ENABLED_KV_KEY, TRIAL_KILL_SWITCH_CACHE_MS — Kill switchTRIAL_EXPIRE_BATCH_SIZE, TRIAL_CLEANUP_BATCH_SIZE, TRIAL_CLEANUP_DEADLINE_MS, TRIAL_NODE_DELETION_LOCK_STALE_MS — Expired-trial cron cleanup bounds and stale deletion-lock retryTRIAL_ORCHESTRATOR_OVERALL_TIMEOUT_MS, TRIAL_ORCHESTRATOR_STEP_MAX_RETRIES, TRIAL_ORCHESTRATOR_RETRY_BASE_DELAY_MS, TRIAL_ORCHESTRATOR_RETRY_MAX_DELAY_MS — Orchestrator retry budgetTRIAL_ORCHESTRATOR_NODE_READY_TIMEOUT_MS, TRIAL_ORCHESTRATOR_AGENT_READY_TIMEOUT_MS, TRIAL_ORCHESTRATOR_WORKSPACE_READY_TIMEOUT_MS, TRIAL_ORCHESTRATOR_WORKSPACE_READY_POLL_INTERVAL_MS — Step-level timeoutsTRIAL_VM_SIZE, TRIAL_VM_LOCATION — VM overrides for trial workspacesTRIAL_GITHUB_TIMEOUT_MS — Per-request timeout for the default-branch probe (fetchDefaultBranch); falls back to main on timeout/404/errorTRIAL_KNOWLEDGE_GITHUB_TIMEOUT_MS, TRIAL_KNOWLEDGE_MAX_EVENTS — Fast-path knowledge probe tunables
VM Agent Environment Variables
Container/User
CONTAINER_USER — Optional docker exec -u override; when unset, auto-detects effective devcontainer user
Git Operations
GIT_CREDENTIAL_TIMEOUT — Go duration for credential-helper callbacks to the local VM agent, such as 5s or 1750ms (default: 5s)GIT_EXEC_TIMEOUT — Timeout for git commands via docker exec (default: 30s)GIT_WORKTREE_TIMEOUT — Timeout for git worktree create/remove (default: 30s)WORKTREE_CACHE_TTL — Cache duration for parsed git worktree list results (default: 5s)MAX_WORKTREES_PER_WORKSPACE — Max worktrees allowed per workspace (default: 5)GIT_FILE_MAX_SIZE — Max file size for git/file endpoint (default: 1048576)
File Operations
FILE_LIST_TIMEOUT — Timeout for file listing commands (default: 10s)FILE_LIST_MAX_ENTRIES — Max entries per directory listing (default: 1000)FILE_FIND_TIMEOUT — Timeout for recursive file index (default: 15s)FILE_FIND_MAX_ENTRIES — Max entries returned by file index (default: 5000)
Error Reporting
ERROR_REPORT_FLUSH_INTERVAL — Background error flush interval (default: 30s)ERROR_REPORT_MAX_BATCH_SIZE — Immediate flush threshold (default: 10)ERROR_REPORT_MAX_QUEUE_SIZE — Max queued error entries (default: 100)ERROR_REPORT_HTTP_TIMEOUT — HTTP POST timeout for error reports (default: 10s)
Message Reporting
MSG_MAX_MESSAGE_CONTENT_BYTES — Max single persisted message content before truncation (default: 102400)
ACP (Agent Communication Protocol)
ACP_MESSAGE_BUFFER_SIZE — Max buffered messages per SessionHost for late-join replay (default: 5000)ACP_VIEWER_SEND_BUFFER — Per-viewer send channel buffer size (default: 256)ACP_PING_INTERVAL — WebSocket ping interval for stale connection detection (default: 30s)ACP_PONG_TIMEOUT — WebSocket pong deadline after ping (default: 10s)ACP_PROMPT_TIMEOUT — Max ACP prompt runtime for workspace sessions; 0 = no timeout (default: 0)ACP_TASK_PROMPT_TIMEOUT — Max ACP prompt runtime for task-driven sessions (default: 6h)ACP_PROMPT_CANCEL_GRACE_PERIOD — Grace wait after cancel before force-stop (default: 5s)ACP_PROMPT_RETRY_MAX_RETRIES — Max transient provider prompt retries after the initial attempt (default: 2)ACP_PROMPT_RETRY_INITIAL_BACKOFF — Initial backoff before retrying transient provider prompt errors (default: 15s)ACP_PROMPT_RETRY_MAX_BACKOFF — Max exponential backoff for transient provider prompt retries (default: 2m)ACTIVITY_REREPORT_INTERVAL — Re-send prompting activity while a prompt is active (default: 60s)ACTIVITY_TERMINAL_REPORT_ATTEMPTS — Retry attempts for terminal activity reports (idle, recovering, error) (default: 5)ACTIVITY_TERMINAL_REPORT_BACKOFF — Backoff between terminal activity report retries (default: 1s)ACP_IDLE_SUSPEND_TIMEOUT — Idle timeout before auto-suspending agent session (default: 30m)ACP_NOTIF_SERIALIZE_TIMEOUT — Max wait for previous session/update processing before delivering next (default: 5s)
Events
MAX_NODE_EVENTS — Max node-level events retained in memory (default: 500)MAX_WORKSPACE_EVENTS — Max workspace-level events retained in memory (default: 500)
System Info
SYSINFO_DOCKER_TIMEOUT — Timeout for Docker CLI commands during system info collection (default: 10s)SYSINFO_VERSION_TIMEOUT — Timeout for version-check commands (default: 5s)SYSINFO_CACHE_TTL — Cache duration for system info results (default: 5s)
