Reference
Every STASO_* environment variable read by the SDK, CLI, and integrations.
Kwargs passed directly to st.init(...) always override environment variables. The SDK reads env vars at init time — changing them after init has no effect.
All variables
| Name | Default | Used by | Purpose |
|---|---|---|---|
STASO_API_KEY | — (required) | st.init, st.guard, all integrations | Workspace or org API key. Sent as the X-API-Key header. |
STASO_AGENT_NAME | — (required) | st.init, st.guard | Logical agent name. Shown in the dashboard and used to derive agent_id. |
STASO_BASE_URL | https://api.staso.ai | st.init, st.guard | Staso backend URL. Override for self-hosted installs. |
STASO_ENVIRONMENT | default | st.init, st.guard | Logical environment tag — e.g. prod, staging, dev. |
STASO_WORKSPACE_SLUG | default | st.init, st.guard | Workspace slug. Required when the API key is workspace-scoped. |
STASO_DEBUG | false | st.init | Set to 1 or true for verbose SDK logging. |
STASO_GUARD_ENABLED | true | Integrations, hook subprocesses | Set to false to short-circuit every guard check to allow inside patch_openai / patch_anthropic and the Claude Code / Codex hooks. |
STASO_GUARD_FAIL_CLOSED | false | st.guard | When true, transport failures return action="block" instead of "allow". Use this only after you trust your network and backend reachability. |
STASO_GUARD_TIMEOUT | 10.0 | st.guard, hook subprocesses | HTTP timeout in seconds for each guard evaluation call. |
STASO_AUTO_SYNC | unset | staso sync, CLI hook installers | Set to 1 to auto-run config sync on SessionStart hooks for Claude Code and Codex. |
STASO_VCS_COMMIT_SHA | auto-detected | st.init (git capture) | Override the captured commit SHA. Use this in CI where .git may be shallow or absent. |
STASO_VCS_BRANCH | auto-detected | st.init (git capture) | Override the captured branch name. |
STASO_VCS_REPO_URL | auto-detected | st.init (git capture) | Override the captured repository URL. |
Usage with .env
# .env
STASO_API_KEY=ak_live_...
STASO_AGENT_NAME=support-bot
STASO_ENVIRONMENT=prod
STASO_WORKSPACE_SLUG=defaultimport os
import staso as st
from dotenv import load_dotenv
load_dotenv()
st.init() # picks up STASO_API_KEY and STASO_AGENT_NAMEUsage in CI
GitHub Actions example — inject VCS metadata at deploy time so runtime doesn't need a git checkout:
- name: Deploy
env:
STASO_API_KEY: ${{ secrets.STASO_API_KEY }}
STASO_AGENT_NAME: support-bot
STASO_ENVIRONMENT: prod
STASO_VCS_COMMIT_SHA: ${{ github.sha }}
STASO_VCS_BRANCH: ${{ github.ref_name }}
STASO_VCS_REPO_URL: ${{ github.server_url }}/${{ github.repository }}
run: python -m my_agent