animawake docs

Reference

Environment and self-hosting

The services that make up Animawake, how to run them locally, and every environment variable they read.

Most people use the hosted service at app.animawake.com. This page is for running Animawake yourself, for development or on your own infrastructure.

#Services

Service Source Runs Default port
PostgreSQL 16 with pgvector docker-compose.yml Stores everything, including embeddings. 5432
Redis 7 docker-compose.yml Cache, task queue, and real-time channels. 6379
API apps/api Django, served over ASGI by daphne, with REST and WebSockets. Runs migrations on start. 8000
Worker apps/api Huey consumers for the default and heavy queues: embeddings, dreams, and other background work. none
MCP server apps/mcp The MCP endpoint and OAuth for clients. 8000 (set PORT)
Web portal apps/web SvelteKit on Node. Serves the portal and these docs. 3000 in production, 5173 in development

The API and the worker are the same image: apps/api/start.sh starts the API when PROCESS_TYPE=web (the default) and the worker when PROCESS_TYPE=worker. The nightly dream runs as a periodic task inside the worker at 06:00 UTC.

#Run locally

  1. Start the databases:

    Terminal
    cp .env.example .env    # set POSTGRES_PASSWORD
docker compose up -d

  2. Configure the API. Copy apps/api/.env.example to apps/api/.env, then set at least:

    .env
    DEBUG=True
SECRET_KEY=a-long-random-string
DATABASE_URL=postgres://animawake:<password>@localhost:5432/animawake
REDIS_URL=redis://localhost:6379/0
OPENAI_API_KEY=sk-...

    Use PostgreSQL: the migrations need the pgvector extension, so SQLite does not work.

  3. Install and start the API:

    Terminal
    python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cd apps/api
python manage.py migrate
python manage.py runserver

    With DEBUG=True, background tasks run immediately in the API process, so you do not need a worker.

  4. Start the portal:

    Terminal
    cd apps/web
npm install
npm run dev

    The dev server proxies /api, /auth, /accounts, /admin, and /oauth to http://localhost:8000.

  5. Optional: load demo data. With DEBUG=True:

    Terminal
    python manage.py seed_demo

    This creates the user demo@local.test (password demo-password-123), the workspace "Demo Household" at /demo, three entities, projects, and devices. It is safe to run more than once.

scripts/dev.sh (macOS) and scripts/dev-linux.sh (Linux) start the API, portal, and desktop app in terminal windows. They expect a root .env and a running PostgreSQL, and they do not start the MCP server or a worker.

To run tests that use vector fields, install the extension in the template database first:

Terminal
docker exec animawake-postgres psql -U animawake -d template1 -c "CREATE EXTENSION IF NOT EXISTS vector;"

#API environment

#Required in production

Variable Purpose
SECRET_KEY Django secret. Must be set and must not start with django-insecure. Also the root for key hashing and encryption; see below.
DATABASE_URL PostgreSQL connection string. The separate DB_* variables also work.
REDIS_URL Redis connection string. REDIS_PUBLIC_URL is accepted as a fallback.
MCP_INTERNAL_SECRET Shared secret between the API and the MCP server. Set the same value on both.

#Hosts and URLs

Some defaults point at animawake.com and others at localhost. The defaults below apply with DEBUG off. Set each of these for your domain:

Variable Purpose
ALLOWED_HOSTS Host names the API answers to, comma-separated. Default localhost,127.0.0.1.
CORS_ALLOWED_ORIGINS Origins allowed to call the API from a browser. Default empty.
CSRF_TRUSTED_ORIGINS Origins trusted for session writes. Default https://app.animawake.com,https://api.animawake.com.
SESSION_COOKIE_DOMAIN Cookie domain. Default .animawake.com.
LOGIN_REDIRECT_URL, LOGOUT_REDIRECT_URL Where sign-in and sign-out return to. Default https://app.animawake.com.
API_BASE_URL, WEB_BASE_URL Public API and portal URLs, used in links such as proposal review URLs. Defaults http://localhost:8000 and http://localhost:3000.
ANIMAWAKE_PORTAL_URL Portal URL used in device pairing links. Default https://app.animawake.com.
SITE_ID Django sites framework ID for social sign-in.

#Model providers

Variable Purpose
OPENAI_API_KEY Embeddings (text-embedding-3-small). Required for search. Workspaces can add their own key.
ANTHROPIC_API_KEY The first wake conversation and startup narratives.
LLM_SYNTHESIS_MODEL OpenAI model for synthesis, and the fallback for startup narratives. Default gpt-4o.
AUTO_TAG_THRESHOLD Similarity needed for automatic tagging during dreams. Default 0.55.
DREAM_MAX_RUNTIME_SECONDS Stop a dream after this long. Default 1800.

#Integrations and storage

Variable Purpose
GITHUB_APP_ID, GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET, GITHUB_APP_WEBHOOK_SECRET, GITHUB_APP_PRIVATE_KEY The GitHub App for repository access. The private key is a base64-encoded PEM.
GOOGLE_INTEGRATIONS_CLIENT_ID, GOOGLE_INTEGRATIONS_CLIENT_SECRET, GOOGLE_INTEGRATIONS_REDIRECT_URI Google services for entities.
CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_R2_ACCESS_KEY, CLOUDFLARE_R2_SECRET_KEY Object storage for screenshots and media. All three enable it. Bucket names and URLs have their own variables.
MEDIA_ROOT Local media folder when object storage is off.
DISCORD_WEBHOOK_URL Channel for notifications that belong to no workspace, such as the nightly summary across all entities. Workspace notifications, such as missed dreams, go only to the workspace's own Discord and never fall back to this URL.
SENTRY_DSN, SENTRY_ENVIRONMENT Error reporting.

Sign-in with Google and GitHub is configured as social applications in the Django admin (/admin/), not with environment variables. Sign-up is invite-only: a new account is created only when the verified email matches a waitlist entry marked as invited, which you do from the waitlist in the Django admin.

#Continuity journal

Variable Purpose
CONTINUITY_CAPTURE_ENABLED True to accept transcripts from the CLI. Default False.
CONTINUITY_ACTIVE_KEY_ID, CONTINUITY_ENCRYPTION_KEYS_JSON Fernet keys for journal encryption, as {"<id>": "<key>"}, and the one in use.
CONTINUITY_ACTIVE_HMAC_KEY_ID, CONTINUITY_HMAC_KEYS_JSON HMAC keys for journal integrity, in the same form.
CONTINUITY_MAX_BATCH_MESSAGES, CONTINUITY_MAX_PART_BYTES, CONTINUITY_MAX_BATCH_BYTES, CONTINUITY_MAX_ATTACHMENT_BYTES Size limits. Defaults: 200 messages, 128 KiB, 16 MiB, 8 MiB.

apps/api/.env.example shows how to generate the keys.

#Process control (start.sh)

Variable Purpose
PROCESS_TYPE web (default) or worker.
PORT Port for the API. Default 8000.
DJANGO_SUPERUSER_EMAIL, DJANGO_SUPERUSER_PASSWORD Create an admin user on start if it does not exist.
RUN_BACKFILL_EMBEDDINGS true to backfill missing embeddings for sessions, decisions, and traces on start. Other memory types are not backfilled.

#About SECRET_KEY

API key hashes and encrypted secrets (such as workspace OpenAI keys) use keys derived from SECRET_KEY. Changing SECRET_KEY invalidates every ent_, fam_, and usr_ key and makes stored encrypted secrets unreadable. Choose it once and keep it safe. FERNET_KEY appears in older examples but is not read.

#MCP server environment

Variable Purpose
ANIMAWAKE_API_URL The API the server calls. Default https://api.animawake.com.
DJANGO_API_URL API URL for OAuth callbacks. Defaults to ANIMAWAKE_API_URL.
MCP_INTERNAL_SECRET Same value as on the API.
PORT Listening port. Default 8000.
MCP_OAUTH_ALLOW_DYNAMIC Allow dynamic client registration. Default true.
MCP_RATELIMIT_PER_MINUTE, MCP_RATELIMIT_BURST General rate limit per IP. Defaults 600 and 120.
MCP_OAUTH_RATELIMIT_PER_MINUTE, MCP_OAUTH_RATELIMIT_BURST Rate limit for OAuth and /whoami. Defaults 30 and 15.

The MCP rate limiter keeps its counters in memory, per process.

The OAuth rules are not configurable. The API enforces them in apps/api/core/views_mcp_oauth.py: PKCE with S256 is always required, redirect URIs must match the allowlist described in Security, and pre-registered Claude Desktop clients must present their client secret at the token endpoint. To allow another redirect host, change that file.

#Web portal environment

Variable Purpose
VITE_API_URL The API's public URL, set at build time.
VITE_MCP_URL The MCP server's public URL, shown on Connect pages. Default https://mcp.animawake.com.
VITE_PLAYER_WS_URL Local desktop app WebSocket. Default ws://127.0.0.1:18789/ws.
VITE_SENTRY_DSN Error reporting.
ORIGIN The portal's public origin, required by the Node server in production.
DOCS_PATH Folder with these docs. Defaults to docs/app, searched from the working directory upward.

#Self-hosting checklist

  1. Generate a strong SECRET_KEY and MCP_INTERNAL_SECRET, and store them safely.
  2. Point every host and URL variable at your domains.
  3. Run the API, a worker, the MCP server, and the portal, plus PostgreSQL with pgvector and Redis.
  4. Create an admin user, add the Google or GitHub social application in /admin/, and mark your own waitlist entry as invited.
  5. Set OPENAI_API_KEY, and ANTHROPIC_API_KEY if you want first wake and startup narratives.
  6. Point clients and the CLI at your servers with ANIMAWAKE_MCP_URL and ANIMAWAKE_API_URL.