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.

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`.

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) or `inprocess` (run inside the queue-worker process — no Docker socket needed, but no `input()`/pause support)

With SANDBOX_EXECUTOR=k8s_pod and TRUSTED_EXECUTOR=inprocess, no process needs a Docker socket — this is the configuration the Helm chart uses. inprocess runs trusted code with the worker’s own environment and credentials, so only enable shared_pool on functions you’d trust with them.

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

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

​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

Executors

Kubernetes executor (`SANDBOX_EXECUTOR=k8s_pod`)

Sandbox Containers

Agent Processing

Tool Results

Scaling

Resource Limits (Docker)

Database

ClickHouse (Optional)

Declarative Config