Reference: Environment variables

Configuration the AcasoOS instance needs to expose for the console to work. Set these in your AcasoOS deployment's environment — the console reads no env at runtime because it is a static bundle.

CORS

ACASO_CONSOLE_ORIGINS

Comma-separated list of fully-qualified origins allowed to call AcasoOS from a browser.

• Default (production): empty. No console access until explicitly configured.
• Default (dev): http://localhost:3000,http://localhost:3001.
• Production value: https://os.aca.so.
• Multiple origins: comma-separated, no spaces. https://os.aca.so,https://staging.os.aca.so works.

The setting feeds FastAPI's CORS middleware with:

Setting	Value
allow_origins	ACASO_CONSOLE_ORIGINS.split(',')
allow_credentials	False
allow_headers	Authorization, Content-Type, X-Acaso-User-Id, X-Request-Id
allow_methods	GET, POST, PATCH, DELETE, OPTIONS

Warning: Wildcard * is rejected at app startup with a clear configuration error. There is no "allow everything" escape hatch by design.

Restart the backend after changing ACASO_CONSOLE_ORIGINS. The value is read once at startup.

Session lifecycle

ACASO_SESSION_TTL_SECONDS

The TTL applied to session keys minted by POST /v1/auth/session.

• Default: 28800 (8 hours).
• Minimum recommended: 3600 (1 hour). Going lower forces re-paste inside one workday.
• Maximum recommended: 86400 (24 hours). Going higher widens the sessionStorage attack surface.

ACASO_SESSION_CLEANUP_GRACE_DAYS

Days after a session's expires_at before the cleanup job hard-deletes the row from dh_api_keys.

• Default: 7. Older expired rows are useful for audit-log retention; beyond that they are noise.

The cleanup job runs in the worker (make worker) and only touches rows where kind = 'session' AND expires_at < NOW() - INTERVAL '<value> days'.

Database

DATABASE_URL

The application connection string. Connects as the non-privileged acaso_app role so RLS policies fire. See Architecture for the role split.

ADMIN_DATABASE_URL

The migration connection string. Connects as the acaso superuser. Use this only for make migrate and DDL; runtime application code must not touch it.

Agent registration

ACASO_AGENT_MODULES

Comma-separated list of Python module paths that contain register_agent(...) calls. The code default lists the example agents (agenthub.examples.*) as a local-dev convenience; production and client deployments set it explicitly — the client's agenthub.custom.<client_slug>.* modules, examples excluded. An empty string loads no agents.

ACASO_MCP_TOOL_MODULES

Comma-separated list of Python module paths whose import runs register_mcp_tool(...) calls. This is how internal (non-agent) tools are published on AgentHub's single Streamable-HTTP MCP endpoint at /mcp (ADR-0020), consumed by LLM hosts such as Claude Desktop and IDEs.

• Default: empty — no internal tools are exposed over MCP.
• Agents-as-tools (agent.<name>) are governed independently by each agent's protocols attribute (add "mcp"), not by this variable.
• Inspect what is live with GET /v1/mcp/tools; the console surfaces the same read-only inventory (exposure is code-declared — there is no console setup).

ACASO_PUBLIC_BASE_URL

Optional. The public base URL (scheme + host, e.g. https://os.aca.so) used to build the absolute url field in each agent's A2A Agent Card (GET /v1/agents/<name>/.well-known/agent-card.json, ADR-0019) when AgentHub runs behind a reverse proxy or load balancer.

• Default: empty — the Agent Card URL falls back to the inbound request host.

Observability

SENTRY_DSN

When set, the AcasoOS SDK initialises Sentry at import time. The console's Sentry integration runs independently in the browser; PII and auth credentials are scrubbed from breadcrumbs and payloads via beforeBreadcrumb and beforeSend hooks.

White-label branding (console)

For a dedicated single-tenant deployment the console can read as the client's own brand. These NEXT_PUBLIC_BRAND_* variables are read by the console build (not the backend), baked into the static export — so rebuild the console after changing them. All optional; unset everything for the stock acaso look. Full walkthrough: the White-labeling the console section of Standalone deployment.

NEXT_PUBLIC_BRAND_NAME

The brand word, bolded in the sidebar wordmark. Setting it also derives the product name (Natura → Natura OS) used in the browser title and across all UI copy.

NEXT_PUBLIC_BRAND_PRODUCT_NAME · NEXT_PUBLIC_BRAND_WORDMARK_SUFFIX

Override the derived product name, or change / hide the muted OS suffix in the wordmark.

NEXT_PUBLIC_BRAND_LOGO_SRC · _TILE · _SIZE · NEXT_PUBLIC_BRAND_FAVICON_SRC

Point at a logo mark placed under the console's public/ directory (e.g. /brand/natura-mark.svg), with optional control over the tile background painted behind it and its size, plus a custom favicon.

NEXT_PUBLIC_BRAND_COLOR

A single base hex, treated as the brand "500". The full light→dark ramp is generated from it, so every accent, border, focus ring, and ambient glow re-themes from the one value.