Skip to main content
All configuration is via environment variables prefixed AWAITHUMANS_. The server reads these once at startup; restart the process to pick up changes.

​
Two namespaces under one prefix

The AWAITHUMANS_ prefix is shared by two unrelated consumers — pay attention when filling a .env file:
VariableRead byUsed for
AWAITHUMANS_URLSDK onlyTells await_human() where the server lives.
AWAITHUMANS_ADMIN_API_TOKENBothServer gates admin routes with it; SDK sends it as bearer.
Every other AWAITHUMANS_* on this pageServer onlyNot read by the SDK.
The server silently ignores any AWAITHUMANS_* key in .env that it doesn’t recognize — so a shared .env containing AWAITHUMANS_URL=… for the agent and AWAITHUMANS_PAYLOAD_KEY=… for the server boots cleanly. If a key looks like a typo (no matching server field), the server emits a WARNING at startup listing every unrecognized AWAITHUMANS_* key — check that line if you suspect a misconfigured server var was silently dropped. Prior to v0.1.3 the server would crash on boot with a pydantic extra_forbidden error if any SDK-side key was present in .env. If you’re hitting that, upgrade.

​
Required

VariableDescription
AWAITHUMANS_PAYLOAD_KEY32-byte urlsafe-base64 string. Root encryption key for sessions + magic links + Slack OAuth tokens. NEVER rotate after first deploy.
AWAITHUMANS_ADMIN_API_TOKENBearer token your agent passes via Authorization: Bearer .... Generate with secrets.token_urlsafe(32).
AWAITHUMANS_PUBLIC_URLPublic-facing URL (e.g. https://reviews.acme.com). Used for OAuth redirects, magic-link URLs, dashboard click-throughs.
In dev (awaithumans dev), the CLI auto-generates these for you and writes the values to ~/.awaithumans-dev.json.

​
Database

VariableDefaultDescription
AWAITHUMANS_DATABASE_URL(none)Full Postgres URL. Overrides the SQLite default.
AWAITHUMANS_DB_PATH.awaithumans/dev.db (dev only)SQLite file path. Used when DATABASE_URL is unset.
AWAITHUMANS_ALLOW_EPHEMERAL_DBfalseAcknowledges that SQLite-in-production is intentional. Suppresses the durability warning. See “Ephemeral SQLite warning” below.
# SQLite (dev / single-user)
AWAITHUMANS_DB_PATH=/var/lib/awaithumans/data.db

# Postgres (production)
AWAITHUMANS_DATABASE_URL=postgresql://user:pass@host:5432/dbname
The .awaithumans/dev.db default is only honored by awaithumans dev (the local development CLI). awaithumans serve (the production entrypoint, and the default Docker CMD) refuses to start unless one of AWAITHUMANS_DATABASE_URL or AWAITHUMANS_DB_PATH is set explicitly — this prevents the silent-data-loss footgun where a container restart on an ephemeral filesystem wipes the SQLite file.

​
Ephemeral SQLite warning

When AWAITHUMANS_ENVIRONMENT=production and the server is on SQLite (either via AWAITHUMANS_DB_PATH or an explicit sqlite:// DATABASE_URL), the lifespan emits a loud multi-line WARNING explaining the data-loss risk and pointing at the two fixes. In most container runtimes — Azure Container Apps, plain Docker without -v, k8s without a PVC, Render free tier — the SQLite path lives on an ephemeral overlay filesystem. Every container restart wipes the task store and the audit trail, silently. To resolve:
  • Move to Postgres (recommended for any deployment you care about): set AWAITHUMANS_DATABASE_URL=postgresql://....
  • Confirm the SQLite path is durable in your runtime’s terms (a mounted volume, a PersistentVolumeClaim, an Azure Files share, etc.). The Dockerfile declares VOLUME ["/var/lib/awaithumans"], but several runtimes ignore that directive — don’t trust it as the only line of defense.
Once durability is confirmed, set AWAITHUMANS_ALLOW_EPHEMERAL_DB=true to acknowledge the configuration and suppress the warning. An audit-level INFO record is still emitted so the decision shows up in logs.

​
Server

VariableDefaultDescription
AWAITHUMANS_HOST0.0.0.0Listen interface.
AWAITHUMANS_PORT3001Listen port.
AWAITHUMANS_ENVIRONMENTdevelopmentSet to production to enable strict checks (HTTPS required, etc).
AWAITHUMANS_LOG_LEVELINFOOne of DEBUG, INFO, WARNING, ERROR.

​
CORS

VariableDefaultDescription
AWAITHUMANS_CORS_ORIGINS*Comma-separated list. Bare * means any origin reads, no credentials. Specific origins flip credentials ON.
The server validates CORS at boot — plain http:// origins outside localhost are rejected, mixed *-with-explicit lists are rejected. See Security.

​
Slack channel

VariableDescription
AWAITHUMANS_SLACK_BOT_TOKENBot token (xoxb-...). Single-workspace mode.
AWAITHUMANS_SLACK_SIGNING_SECRETRequired for any Slack mode. Verifies inbound webhooks.
AWAITHUMANS_SLACK_CLIENT_IDOAuth multi-workspace install.
AWAITHUMANS_SLACK_CLIENT_SECRETOAuth multi-workspace install.
AWAITHUMANS_SLACK_INSTALL_TOKENOperator-only secret gating /oauth/start. Required for multi-workspace mode.
AWAITHUMANS_SLACK_OAUTH_SCOPESOverride default scope set. Rare.
See Slack for the install flow.

​
Email channel

VariableDefaultDescription
AWAITHUMANS_EMAIL_TRANSPORT(none)One of resend, smtp, logging, noop.
AWAITHUMANS_EMAIL_FROM(none)Sender address. Required if a transport is set.
AWAITHUMANS_EMAIL_FROM_NAME(none)Display name.
AWAITHUMANS_EMAIL_REPLY_TO(none)Reply-To header.
AWAITHUMANS_RESEND_KEY(none)Resend API key. Required for resend transport.
AWAITHUMANS_SMTP_HOST(none)Required for smtp transport.
AWAITHUMANS_SMTP_PORT587
AWAITHUMANS_SMTP_USER(none)
AWAITHUMANS_SMTP_PASSWORD(none)
AWAITHUMANS_SMTP_USE_TLSfalseImplicit TLS (port 465). Rare.
AWAITHUMANS_SMTP_START_TLStrueSTARTTLS on port 587. Most common.
See Email.

​
Verifier

VariableDescription
ANTHROPIC_API_KEYDefault for claude provider.
OPENAI_API_KEYDefault for openai provider.
GEMINI_API_KEYDefault for gemini provider.
AZURE_OPENAI_API_KEYDefault for azure provider.
AZURE_OPENAI_ENDPOINTRequired for azure provider.
These are read by Settings.get_secret(env_name) at verification time. Override per-task via VerifierConfig.api_key_env=.... See Verifier.

​
.env file

The server loads .env from the working directory at startup. Useful for local dev: 
AWAITHUMANS_PAYLOAD_KEY=tlR5UCElY4QIjThpO4TlL1GzTzXrQQJYa3BtvZ0FOBQ
AWAITHUMANS_ADMIN_API_TOKEN=YrKxVj9FOaEP2UnVQWf1kT87Ld6sPmA9XgB3ZNzuIqs
AWAITHUMANS_SLACK_BOT_TOKEN=xoxb-...
ANTHROPIC_API_KEY=sk-ant-...
Variables in the actual environment override the file. For Docker / Kubernetes, prefer real env vars.

​
Logging

The root logger writes structured lines to stdout: 
2026-05-12T08:00:01.123Z [INFO] awaithumans.server.routes.tasks request_id=abc123 — Task tsk_4f8 created
A scrubbing filter on the root handler redacts known credential patterns from every record before it reaches stdout — sk-..., Bearer ..., password=..., X-Admin-Token: .... Even if upstream code accidentally logs a credential, it gets [REDACTED] before egress. For audit-style structured output (one JSON object per line), wrap with jq downstream — the format is grep-friendly by design.

​
Discovery file

In dev mode, awaithumans dev writes ~/.awaithumans-dev.json: 
{
  "url": "http://localhost:3001",
  "admin_token": "..."
}
The SDK (Python and TS) reads this file when no env vars are set, so await_human() calls in your agent script auto-discover the running dev server. The file is chmod 0600 and lives in the user’s home — never check it in. In production, set AWAITHUMANS_URL and AWAITHUMANS_ADMIN_API_TOKEN in your agent’s environment instead.