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: 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

In dev (awaithumans dev), the CLI auto-generates these for you and writes the values to ~/.awaithumans-dev.json.

​
Database

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

​
CORS

The server validates CORS at boot — plain http:// origins outside localhost are rejected, mixed *-with-explicit lists are rejected. See Security.

​
Slack channel

See Slack for the install flow.

​
Email channel

See Email.

​
Verifier

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:
Variables in the actual environment override the file. For Docker / Kubernetes, prefer real env vars.

​
Logging

The root logger writes structured lines to stdout:
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:
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.