Environment Variables

Required

Variable	Description
`SECRET_KEY`	JWT signing key (auto-generated by install script)
`ENCRYPTION_KEY`	Fernet key for encrypting stored credentials (LLM API keys, DB passwords)
`DATABASE_PASSWORD`	PostgreSQL password
`SUPERADMIN_EMAIL`	Admin user created on first startup
`DOMAIN`	Your domain for Caddy auto-HTTPS (e.g., `sinas.example.com`)

Authentication

Variable	Default	Description
`AUTH_MODE`	`otp`	One of `otp`, `password`, `password+otp`. See Authentication for the differences.
`SUPERADMIN_PASSWORD`	(none)	Seed password for the superadmin. Only used when `AUTH_MODE` includes `password`. Setting this and restarting acts as a password-reset escape hatch.
`TOKEN_EXCHANGE_DEFAULT_ROLE`	`GuestUsers`	Role assigned to users auto-provisioned via `POST /auth/token/exchange`. See Token Exchange.
`OAUTH_BIND_BROWSER_SESSION`	`true`	Bind connector OAuth (authorization-code) flows to the browser that started them via an HttpOnly nonce cookie — prevents account-linking CSRF. Set `false` only for split-origin local dev (console and API on different ports); keep `true` in production.
`JWT_ALGORITHM`	`HS256`	Access-token signing. `RS256` signs with an RSA keypair and publishes it at `/.well-known/jwks.json` so external services can verify tokens offline. See Verifying Sinas Tokens.
`JWT_ISSUER`	instance URL	`iss` claim on RS256 access tokens.
`JWT_AUDIENCE`	`sinas`	`aud` claim on RS256 access tokens.
`JWT_PRIVATE_KEY`	(none)	RS256 private key as PEM content. When neither this nor `JWT_PRIVATE_KEY_FILE` is set, a keypair is auto-generated and stored encrypted in the database.
`JWT_PRIVATE_KEY_FILE`	(none)	RS256 private key as a file path.

SMTP

Required when AUTH_MODE is otp or password+otp. Skip entirely for password mode (airgapped deployments).

Variable	Default	Description
`SMTP_HOST`	(none)	SMTP server hostname (e.g., `smtp.sendgrid.net`)
`SMTP_PORT`	`587`	SMTP port
`SMTP_USER`	(none)	SMTP username
`SMTP_PASSWORD`	(none)	SMTP password or API key
`SMTP_DOMAIN`	(none)	Email “from” domain (e.g., `example.com`)

Application

Variable	Default	Description
`DEBUG`	`false`	Enable verbose logging
`CORS_ORIGINS`	(none)	Comma-separated allowed origins
`ACCESS_TOKEN_EXPIRE_MINUTES`	`15`	JWT access token lifetime
`REFRESH_TOKEN_EXPIRE_DAYS`	`30`	Refresh token lifetime
`OTP_EXPIRE_MINUTES`	`10`	OTP code validity
`OTP_MAX_ATTEMPTS`	`2`	Wrong OTP guesses before invalidation

Rate Limiting

Variable	Default	Description
`RATE_LIMIT_LOGIN_IP_MAX`	`10`	Max login requests per IP per window
`RATE_LIMIT_LOGIN_EMAIL_MAX`	`5`	Max login requests per email per window
`RATE_LIMIT_OTP_IP_MAX`	`10`	Max OTP verify requests per IP per window
`RATE_LIMIT_WINDOW_SECONDS`	`900`	Rate limit window (15 minutes)

Function Execution

Variable	Default	Description
`FUNCTION_TIMEOUT`	`300`	Max execution time in seconds
`MAX_FUNCTION_MEMORY`	`512`	Memory limit in MB
`MAX_FUNCTION_CPU`	`1.0`	CPU cores per function
`MAX_FUNCTION_STORAGE`	`1g`	Disk storage limit
`FUNCTION_CONTAINER_IDLE_TIMEOUT`	`3600`	Idle container cleanup (seconds)
`ALLOW_PACKAGE_INSTALLATION`	`true`	Allow `pip install` in functions
`ALLOWED_PACKAGES`	(all)	Comma-separated package whitelist
`MAX_EXECUTION_DEPTH`	(= workers)	Max nesting depth for execution chains (a function/agent invoking another execution). A deeper call is rejected fast instead of deadlocking the shared pool. Defaults to `DEFAULT_WORKER_COUNT`; `0` disables.
`SHARED_POOL_RESERVE`	`0`	Shared-worker slots reserved for nested calls so a parent waiting on a child can’t starve the pool. `0` = off. For full single-chain safety set to `MAX_EXECUTION_DEPTH - 1`.

Optional Features

Both default on. Turning one off removes the capability — affected endpoints reject explicitly rather than half-working.

Variable	Default	Description
`CODE_EXECUTION_ENABLED`	`true`	`false` disables all execution of user-supplied code: Functions and the agent `codeExecution` tool. The tool is not advertised to the model, function execution is refused at every trigger (API, webhook, schedule, agent, CDC), and sandbox/shared-worker startup is skipped entirely — no pool, no per-execution pods, no executor image. The single biggest footprint reduction available.
`BUILTIN_DATABASE_ENABLED`	`true`	`false` skips creating the `sinas_data` database and its default Database Connection at startup, for deployments that only use their own connections. Does not affect the platform’s own PostgreSQL, and an already-created database and record are left untouched (so the toggle is reversible and non-destructive).

Usage Metering (Optional)

Default off. When enabled, every operation (function execution, code execution, query, agent invocation, file upload, other tool calls) increments a live counter; the scheduler snapshots it durably and pushes the cumulative period-to-date total to an external collector. Pure emission — nothing is enforced on the instance, no limits are pulled down, and an unreachable collector or Redis blip never affects platform behavior (the next heartbeat self-heals). Intended for managed/multi-instance operators.

Variable	Default	Description
`METERING_ENABLED`	`false`	Master switch.
`PLATFORM_REPORT_URL`	(none)	Platform POST endpoint receiving heartbeat JSON (`sinas.metering/v2`): cumulative totals + `by_kind` as decimal strings, `Idempotency-Key` per push. The response carries the Platform-issued billing period (first report goes out as `canonical_period_id: "init"`).
`PLATFORM_API_KEY`	(none)	Opaque instance token, sent as `Authorization: Bearer <key>`. Never logged.
`METERING_INSTANCE_ID`	`DOMAIN`	Identifier for this instance in reports.
`METERING_SNAPSHOT_MINUTES`	`5`	Cadence of the durable Redis → Postgres snapshot.
`METERING_PUSH_MINUTES`	`15`	Heartbeat cadence (jittered per instance so fleets don’t push in sync).

Meter integrity: sandbox and shared executor containers/pods receive no Redis/database credentials, so code they run cannot alter the count. TRUSTED_EXECUTOR=inprocess breaks that guarantee (client code runs inside a credential-bearing process) — enabling metering in that mode logs a warning. Metered instances should use docker_shared (Docker) or k8s_shared (Kubernetes), or disabled if shared-pool functions aren’t needed.

Executors

How Sinas runs user code. SANDBOX_EXECUTOR handles untrusted code (untrusted functions and agent code execution) and must isolate every execution; TRUSTED_EXECUTOR handles admin-approved functions (shared_pool=true).

Variable	Default	Description
`SANDBOX_EXECUTOR`	`docker_pool`	`docker_pool` (warm container pool), `docker_ephemeral` (single-use container per execution, baked package image), `k8s_pod` (single-use Kubernetes pod per execution), or `disabled` (reject sandbox executions)
`TRUSTED_EXECUTOR`	`docker_shared`	`docker_shared` (long-lived shared worker containers), `k8s_shared` (long-lived credential-free Kubernetes pods), `inprocess` (run inside the queue-worker process — no Docker socket needed, but no `input()`/pause support), or `disabled` (reject shared-pool executions)
`K8S_TRUSTED_WORKERS`	`2`	Number of warm trusted worker pods (`k8s_shared` only).

On Kubernetes, SANDBOX_EXECUTOR=k8s_pod with TRUSTED_EXECUTOR=k8s_shared is the Helm chart’s default: no process needs a Docker socket, and trusted code runs in warm pods that carry no platform credentials (dispatch latency is an exec round-trip, not a pod cold-start). inprocess remains the smallest-footprint option, but it runs trusted code with the worker’s own environment and credentials — only enable shared_pool on functions you’d trust with them, and don’t combine it with usage metering.

Kubernetes executor (`SANDBOX_EXECUTOR=k8s_pod`)

Requires running in-cluster with a ServiceAccount that can create/get/ list/delete pods and use pods/exec in the sandbox namespace (the Helm chart provisions this).

Variable	Default	Description
`K8S_SANDBOX_NAMESPACE`	(own namespace)	Namespace for sandbox pods
`K8S_SANDBOX_IMAGE`	`FUNCTION_CONTAINER_IMAGE`	Image for sandbox pods (must be pullable by the cluster)
`K8S_SANDBOX_SERVICE_ACCOUNT`	(namespace default)	ServiceAccount assigned to sandbox pods
`K8S_SANDBOX_POD_READY_TIMEOUT`	`120`	Seconds to wait for a sandbox pod to become ready
`K8S_SANDBOX_INSTALL_DEPENDENCIES`	`true`	`pip install` platform dependencies into each pod; set to `false` when they are baked into `K8S_SANDBOX_IMAGE`

Sandbox Containers

Used by SANDBOX_EXECUTOR=docker_pool (the warm pool).

Variable	Default	Description
`SANDBOX_MIN_SIZE`	`4`	Containers to pre-create
`SANDBOX_MAX_SIZE`	`20`	Maximum sandbox containers
`SANDBOX_MIN_IDLE`	`2`	Replenish when idle drops below this
`SANDBOX_MAX_EXECUTIONS`	`100`	Recycle after N executions

Agent Processing

Variable	Default	Description
`MAX_TOOL_ITERATIONS`	`25`	Max consecutive tool-call rounds per message
`MAX_HISTORY_MESSAGES`	`100`	Messages loaded for conversation context
`AGENT_JOB_TIMEOUT`	`600`	Agent job timeout (seconds)
`AGENT_DELEGATE_TIMEOUT`	`600`	How long a parent agent waits for a delegated sub-agent (block mode). Raise together with `AGENT_JOB_TIMEOUT` — in block mode the parent’s own job clock keeps running while it waits
`AGENT_DELEGATE_MODE`	`block`	`block`: parent holds its worker slot while awaiting sub-agents. `suspend`: parent job ends at delegation and a resume job continues the conversation when the children finish (frees the slot)
`AGENT_MAX_DELEGATION_DEPTH`	`5`	Reject agent-to-agent delegation chains deeper than this (`0` disables the bound)
`AGENT_SUBAGENT_QUEUE`	`true`	Route delegated (sub-agent) jobs to the dedicated `queue-agent-sub` worker so parents can never starve their children of worker slots
`CODE_EXECUTION_TIMEOUT`	`120`	Code execution timeout (seconds)

Tool Results

Variable	Default	Description
`TOOL_RESULT_CONTEXT_MAX_SIZE`	`102400`	Max characters of a single tool result entering the LLM context (~25K tokens). Oversized results are truncated structure-aware: JSON lists trimmed to whole elements, long strings clipped, always with a machine-readable `{"_truncated": true, "returned": X, "total": Y}` marker so the model pages instead of retrying. Lower (e.g. `50000`) for a tighter per-turn token budget
`TOOL_RESULT_MAX_SIZE`	`102400`	Max bytes the tool result store persists per result row (distinct from the context cap above)
`TOOL_RESULT_MAX_INLINE`	`5`	Last N tool results kept inline in conversation history
`TOOL_RESULT_RETENTION_DAYS`	`30`	Days stored tool results are retained

Scaling

Variable	Default	Description
`BACKEND_REPLICAS`	`1`	Backend API replicas
`UVICORN_WORKERS`	`4`	Workers per backend replica
`QUEUE_WORKER_REPLICAS`	`2`	Function queue worker replicas
`QUEUE_AGENT_REPLICAS`	`2`	Agent queue worker replicas
`QUEUE_FUNCTION_CONCURRENCY`	`10`	Concurrent functions per worker
`QUEUE_AGENT_CONCURRENCY`	`5`	Concurrent agent jobs per worker
`QUEUE_SATURATION_TIMEOUT_SECONDS`	`21600`	How long a queued function job may wait for a shared-pool slot (deferred retries with backoff) before failing. Bulk ingest drains through this window; `0` = wait forever.
`WORKER_MEMORY_LIMIT`	`1g`	Memory limit per shared worker container (Docker size string).
`QUEUE_AGENT_SUB_REPLICAS`	`2`	Sub-agent queue worker replicas (delegated agent jobs)
`QUEUE_AGENT_SUB_CONCURRENCY`	`5`	Concurrent jobs per sub-agent worker
`DEFAULT_WORKER_COUNT`	`4`	Shared (trusted) worker containers for `shared_pool` functions. Also the default ceiling for `MAX_EXECUTION_DEPTH`.

Resource Limits (Docker)

Variable	Default	Description
`APP_CPU_LIMIT`	`2.0`	Max CPU cores for backend container
`APP_MEMORY_LIMIT`	`2G`	Max RAM for backend container
`APP_CPU_RESERVATION`	`0.5`	Guaranteed CPU cores
`APP_MEMORY_RESERVATION`	`512M`	Guaranteed RAM

Database

Variable	Default	Description
`DATABASE_USER`	`postgres`	PostgreSQL user
`DATABASE_HOST`	`postgres`	PostgreSQL host
`DATABASE_PORT`	`5432`	PostgreSQL port
`DATABASE_NAME`	`sinas`	Database name
`DATABASE_URL`	(built from above)	Full connection string (overrides individual vars)
`REDIS_URL`	`redis://redis:6379/0`	Redis connection string

ClickHouse (Optional)

Variable	Default	Description
`CLICKHOUSE_HOST`	`clickhouse`	ClickHouse host
`CLICKHOUSE_PORT`	`8123`	ClickHouse HTTP port
`CLICKHOUSE_USER`	`default`	ClickHouse user
`CLICKHOUSE_PASSWORD`	(empty)	ClickHouse password
`CLICKHOUSE_DATABASE`	`sinas`	ClickHouse database
`CLICKHOUSE_RETENTION_DAYS`	`90`	Data retention (no S3)
`CLICKHOUSE_HOT_RETENTION_DAYS`	`30`	Hot retention (with S3)
`CLICKHOUSE_S3_ENDPOINT`	(none)	S3 endpoint for tiered storage
`CLICKHOUSE_S3_BUCKET`	(none)	S3 bucket name
`CLICKHOUSE_S3_ACCESS_KEY_ID`	(none)	S3 access key
`CLICKHOUSE_S3_SECRET_ACCESS_KEY`	(none)	S3 secret key
`CLICKHOUSE_S3_REGION`	`us-east-1`	S3 region

Declarative Config

Variable	Default	Description
`CONFIG_FILE`	(none)	Path to YAML config file
`AUTO_APPLY_CONFIG`	`false`	Apply config file on startup

The simplest useful setup requires the required variables plus a configured LLM provider. Everything else (functions, skills, state, etc.) is optional and can be added incrementally.

Getting Started

Platform

Build

Storage

Triggers

Configure

Admin

Environment Variables

Required

Authentication

SMTP

Application

Rate Limiting

Function Execution

Optional Features

Usage Metering (Optional)

Executors

Kubernetes executor (`SANDBOX_EXECUTOR=k8s_pod`)

Sandbox Containers

Agent Processing

Tool Results

Scaling

Resource Limits (Docker)

Database

ClickHouse (Optional)

Declarative Config

​Required

​Authentication

​SMTP

​Application

​Rate Limiting

​Function Execution

​Optional Features

​Usage Metering (Optional)

​Executors

​Kubernetes executor (SANDBOX_EXECUTOR=k8s_pod)

​Sandbox Containers

​Agent Processing

​Tool Results

​Scaling

​Resource Limits (Docker)

​Database

​ClickHouse (Optional)

​Declarative Config

Required

Authentication

SMTP

Application

Rate Limiting

Function Execution

Optional Features

Usage Metering (Optional)

Executors

Kubernetes executor (`SANDBOX_EXECUTOR=k8s_pod`)

Sandbox Containers

Agent Processing

Tool Results

Scaling

Resource Limits (Docker)

Database

ClickHouse (Optional)

Declarative Config