Environment variables

Clowld Space reads environment variables at process startup. After changing one, restart the affected API, web, or daemon process. Docker Compose's docker compose restart does not re-read .env; recreate containers with up -d for changes to take effect.

This page lists deployment-facing configuration only; test variables and internal run variables are not covered here. It is a grouped reference — for full deployment steps, see the self-host quickstart.

Minimum production configuration

DATABASE_URL=postgres://user:password@postgres:5432/clowld?sslmode=require
JWT_SECRET=<long-random-secret>
APP_ENV=production
FRONTEND_ORIGIN=https://clowld.example.com
CLOWLD_APP_URL=https://clowld.example.com
CLOWLD_PUBLIC_URL=https://api.clowld.example.com

You also need to pick an email service, otherwise verification codes and invitations are only written to the server log.

API and database

When setting a shutdown hold on Kubernetes, terminationGracePeriodSeconds must exceed the hold plus the time the actual shutdown needs.

The primary and replica connection limits are independent. Budget their sum across every API process against the PostgreSQL cluster's connection ceiling. Replica connections are recycled after five minutes by default to refresh read-only validation after promotion. Replica connection failures transparently fall back to primary and open a short passive circuit; no background database probe is added. Replica reads have no application-enforced staleness bound, so monitor lag in the database layer and keep consistency-sensitive reads on primary.

Public URLs and browser access

When the frontend and API run on different hosts and the browser talks to the API domain directly, you must set COOKIE_DOMAIN — otherwise the browser cannot read the CSRF cookie: every write request returns 403 CSRF validation failed while reads work fine. Use the narrowest parent domain that covers both hosts (.agent.example.com over .example.com). It spreads the sign-in session cookie to every host under that domain, which is only acceptable when all of those hosts are operated by the same trusted party. After changing it, clear the old cookies on both hosts and sign in again. If you follow the same-origin recipe in the self-host quickstart (the browser only visits the app domain), keep it empty. Do not use an IP address — browsers ignore cookies whose Domain is an IP.

Email and sign-in

Resend

SMTP

SMTP takes priority over Resend whenever SMTP_HOST is non-empty.

Google OAuth

Signup scope

For the exact allowlist evaluation order, see Sign-in and signup.

Attachment storage

When S3_BUCKET is unset, Clowld Space uses local disk.

S3 or compatible storage

Use ATTACHMENT_DOWNLOAD_MODE=proxy when the endpoint — an internal MinIO, for example — is not reachable from the browser.

Local disk

CloudFront

Redis and rate limiting

Deployments behind a reverse proxy must list their real proxy ranges. Do not blanket-trust all sources, or clients can forge forwarded IPs.

The auth rate limits require REDIS_URL; without it, the startup log notes that auth rate limiting is disabled. Invitation limits still run in process-local memory without Redis and become shared across replicas when Redis is configured. If configured Redis becomes temporarily unavailable, auth rate limiting fails open, while invitation creation returns a retryable 503 instead of sending email without protection.

External integrations

Without GITHUB_APP_ID and the private key, PRs still link, mirror, and move issues on merge normally, but cards show no CI or mergeability status, and the "pick from GitHub" repository entry is disabled.

For setup steps, see GitHub integration, Lark bot, Slack bot, and Telegram bot.

Server-side LLM

This group configures server-side assist generation, such as conversation titles; it is not the AI coding tool credentials agents use to execute runs.

CLOWLD_LLM_MAX_RETRIES is the single source for the retry policy. Leave it unset for the default of 2, set 0 to send exactly one request per call, or set 1–5 to cap retries at that many. It is a ceiling, not a quota: only retryable failures consume it, and a success or the caller's own deadline can end the call sooner. Any other value — negative, non-numeric, or above 5 — fails startup instead of being corrected silently. The ceiling is a latency budget: backoff starts at 0.5s and doubles to an 8s cap, so a larger budget would outlast the callers' own deadlines and turn a retryable failure into a timeout. Retries cover connection failures and HTTP 408, 409, 429 and 5xx; all other 4xx responses are returned as-is. The server logs the effective policy at startup as llm retry policy, with no credentials in the line.

CLOWLD_LLM_DISABLE_THINKING is for gateways whose models spend a reasoning ("thinking") pass that dominates the latency budget of the assist calls. When set to true (or 1), the server adds chat_template_kwargs: {"enable_thinking": false} to every request body; gateways that forward the field — vLLM/sglang-style deployments and some GLM/Qwen-style LiteLLM routes — then skip the thinking pass. Standard OpenAI endpoints reject unknown body fields, so only enable this when your upstream accepts it. GPT-5.6-family models already get reasoning_effort: none on the follow-up questions request. Chat auto-titling sends no reasoning field; this switch affects it only when the configured upstream accepts chat_template_kwargs. Accepted values are true/false and 1/0 (case-insensitive); anything else fails startup. The startup log reports the effective state alongside the retry policy.

Two features use this layer, and each one sends chat content to the endpoint you configure:

• Chat auto-titling — the first user message of a new chat session, sent verbatim. Attachments are never included.
• Follow-up questions (the suggestion buttons under an agent reply) — the tail of the conversation: up to 6 messages, with the reply being answered capped at 3000 characters and each older message at 800.

When both the API key and the base URL are empty, this layer is disabled and makes no upstream request at all — neither feature above sends anything. That is the supported configuration when your policy does not allow this layer to send chat content off the deployment: chat sessions keep the title the client derives from the first message, the follow-up question buttons do not appear, and everything else is unaffected.

Daemon configuration

The variables below are read on the computer that runs your agents, not in the API container.

For the internal context that the daemon injects into agent runs, see Task runtime environment.

@/home/clowld/clowld_workspaces/clowld-spac-8e9e35d1c531/cs-534-ff75298c9d0f/workdir/combined_env_en.txt

CLOWLD_CLAUDE_PATH=/opt/bin/claude
CLOWLD_CLAUDE_ARGS=--max-turns 40

Cursor's verified background cleanup requires Linux 6.9 or newer (process-group pidfds), macOS kernel support for process identity queries and audit-token signalling, or a successfully assigned nested Job Object on Windows. On macOS, each process is signalled using a kernel-checked PID version; no same-session group join is required. These macOS APIs are private and checked at capture time. A launch that cannot be claimed returns its original tool result and uses the ordinary idle watchdog, including when the tool watchdog is 0. Already-claimed work remains in flight if cleanup cannot be confirmed. With the tool watchdog set to 0 there is no such boundary at all: claimed background work keeps the run in flight for as long as it lives, so the run is bounded only by CLOWLD_AGENT_TIMEOUT, which is 0 by default.

Owned Cursor background processes are also stopped when the run completes normally, so a background server started by that run does not intentionally survive finalization. macOS can recognize late children through retained original-parent identities, but cannot prove a chain whose intermediate processes disappeared before observation. Such processes, work that leaves the tracked group, or persistent ownership/signalling errors can leave background work behind. Unconfirmed cleanup is logged and never grants a successful-cleanup recovery window; unknown processes are not killed based only on their numeric PID or process group.

Precedence is command-line flag → environment variable → ~/.clowld-space/cli/config.json → built-in default. For watchdog behavior, see Daemon and runtimes.

Persisting daemon configuration

Common daemon-side settings can also be written to ~/.clowld-space/cli/config.json instead of relying on shell environment variables; named profiles keep theirs at ~/.clowld-space/cli/profiles/<name>/config.json:

clowld config set poll_interval 10s
clowld config show

Supported keys:

A few value rules:

• Duration keys accept positive Go durations (such as 10s, 2h); 0s and negative values are rejected. The one exception is agent_timeout: 0s is valid and explicitly disables the run time limit.
• Passing an empty string clears a persisted value and falls back to the env var or built-in default, for example clowld config set poll_interval "".
• max_concurrent_tasks requires a non-negative integer.
• Relative workspaces_root values are converted to absolute paths when saved.

Observability and analytics

Next steps

• Sign-in and signup — sign-in methods and signup restrictions.
• Troubleshooting — symptom-based diagnosis of deployment problems.
• Daemon and runtimes — the daemon-side counterparts of this configuration.

Clowld Space

• Company governance: CLOWLD_COMPANY_GOVERNANCE_ENABLED, CLOWLD_COMPANY_NAME, CLOWLD_COMPANY_EMAIL_DOMAINS, CLOWLD_COMPANY_CEO_EMAIL.
• Model prices: MODEL_PRICING_TIMEZONE, MODEL_PRICING_LITELLM_URL, MODEL_PRICING_MODELS_URL.