Configuration reference

Environment variables for the operator running a Takosumi endpoint. In a Cloudflare setup, pass them with [vars] and wrangler secret put; in a Bun + PostgreSQL setup, pass them as process environment variables. See Run it yourself for the setup steps.

Variables marked secret in the required column must not go into configuration files — pass them from a secret store.

Service-wide

Variable	Required	Default	What it sets
TAKOSUMI_ENVIRONMENT	optional	local	One of local / development / test / staging / production. staging and production fail closed on encryption keys and durable stores. NODE_ENV and ENVIRONMENT are read as fallbacks
TAKOSUMI_DEV_MODE	optional	unset	1 / true / yes / on / enabled lets a non-production process start without setting an encryption key. It has no effect in staging / production
PORT	optional	8788	Listen port when started with bun core/index.ts
TAKOSUMI_DATABASE_URL	required when running the control plane alone with bun core/index.ts	none	PostgreSQL URL for the control plane. DATABASE_URL is read as a fallback. The bundled compose runs control plane and accounts on one connection, so only TAKOSUMI_ACCOUNTS_DATABASE_URL is set there
TAKOSUMI_DB_AUTO_MIGRATE	optional	false	Apply migrations on bun core/index.ts startup. Default verifies read-only. Setting true in staging / production fails startup
TAKOSUMI_DEPLOY_CONTROL_TOKEN	required in production · secret	none	Bearer for the operator API. Used by the CLI and operator clients
TAKOSUMI_METRICS_SCRAPE_TOKEN	optional · secret	none	Bearer for /metrics. /metrics returns 404 until it is set

export TAKOSUMI_ENVIRONMENT=production
export TAKOSUMI_DATABASE_URL="postgres://takosumi:<password>@db.example.com:5432/takosumi"
export TAKOSUMI_DEPLOY_CONTROL_TOKEN="$(openssl rand -hex 32)"

Secret protection

Variable	Required	Default	What it sets
TAKOSUMI_SECRET_STORE_PASSPHRASE	required in staging / production · secret	none	Base material for the AES-GCM key that seals ProviderConnections, state, and plans. Needs 32+ UTF-8 bytes. TAKOSUMI_SECRET_STORE_KEY is read as a fallback
TAKOSUMI_SECRET_STORE_PARTITION_PASSPHRASES	optional · secret	none	JSON mapping partition names to separate passphrases. Omitted partitions derive from the key above
TAKOSUMI_DATABASE_ENCRYPTION_AT_REST	required when bun core/index.ts runs in staging / production	none	Declares encryption at rest as verified. The only value is verified
TAKOSUMI_DATABASE_ENCRYPTION_EVIDENCE	optional	operator-attested	Non-secret text describing what you verified

export TAKOSUMI_SECRET_STORE_PASSPHRASE="$(openssl rand -base64 48)"
export TAKOSUMI_DATABASE_ENCRYPTION_AT_REST=verified
export TAKOSUMI_DATABASE_ENCRYPTION_EVIDENCE="rds-storage-encrypted-kms-key-abc123"

Encryption at rest is judged only by the declared evidence, never inferred from the connection string shape. A control plane started with bun core/index.ts requires this declaration in staging and production.

Sign-in and OIDC

Accounts is the OIDC issuer itself. The issuer you set here is the entry for the dashboard and for products that sign in to Takosumi.

Variable	Required	Default	What it sets
TAKOSUMI_ACCOUNTS_ISSUER	required in Cloudflare setups	http://localhost:<port> in PostgreSQL setups	The public issuer URL. Cloudflare setups do not infer it from the request URL and refuse to start without it
TAKOSUMI_ACCOUNTS_DATABASE_URL	required in PostgreSQL setups	none	PostgreSQL URL for accounts. takosumi accounts migrate reads it too
TAKOSUMI_ACCOUNTS_ES256_PRIVATE_JWK	required for https issuers · secret	none	The P-256 JWK signing id_tokens. Contains the private d. Without it the key changes per process and verification breaks on restart or replica add
TAKOSUMI_ACCOUNTS_ES256_KEY_ID	optional	the JWK's kid	Key id published in the JWKS. Falls back to a per-distribution constant when the JWK has no kid
TAKOSUMI_ACCOUNTS_ES256_PREVIOUS_PUBLIC_JWKS	optional	none	The previous public JWKS to list during key rotation. Never includes private d
TAKOSUMI_ACCOUNTS_OIDC_PAIRWISE_SUBJECT_SECRET	required once a signing key is set · secret	none	Secret used to derive per-client subjects. Startup fails if the signing key is set without it
TAKOSUMI_ACCOUNT_SESSION_HASH_SALT	required · secret	none	Salt for hashing session ids at rest. Cloudflare refuses to start without it; Bun refuses in NODE_ENV=production or TAKOSUMI_ENV=production
TAKOSUMI_ACCOUNTS_CLIENTS	optional	none	JSON array of statically registered OIDC clients. clientId and redirectUris are required; tokenEndpointAuthMethod and allowedScopes may follow
TAKOSUMI_ACCOUNTS_CLIENT_ID / TAKOSUMI_ACCOUNTS_REDIRECT_URIS	optional	none	Short form registering one client. Set both together
TAKOSUMI_ACCOUNTS_CLIENT_SECRET	optional · secret	none	Secret for making the client above confidential. Leave empty for a public PKCE client
TAKOSUMI_ACCOUNTS_CLIENT_AUTH_METHOD	optional	client_secret_post with a secret, else none	One of client_secret_basic / client_secret_post / none
TAKOSUMI_ACCOUNTS_ALLOWED_SCOPES	optional	none	Comma-separated scopes allowed for the client above
TAKOSUMI_ACCOUNTS_UPSTREAM_PROVIDERS	optional	none	JSON array of upstream OAuth / OIDC provider descriptors. References endpoint, client id, and secret by variable name
TAKOSUMI_ACCOUNTS_SUBJECT_SECRET	required when an upstream provider is set · secret	none	Hash secret mapping upstream subjects to Takosumi subjects
TAKOSUMI_ACCOUNTS_UPSTREAM_SESSION_TTL_MS	optional	none	Lifetime (ms) of sessions created by upstream sign-in. Set together with an upstream provider
TAKOSUMI_ACCOUNTS_PASSKEY_RP_ID / TAKOSUMI_ACCOUNTS_PASSKEY_RP_NAME / TAKOSUMI_ACCOUNTS_PASSKEY_ORIGIN	optional	none	Relying party for passkeys. All three are required to start. PostgreSQL setups also read the origin from TAKOSUMI_ACCOUNTS_PASSKEY_RP_ORIGIN
TAKOSUMI_ACCOUNTS_PRIVACY_OPERATIONS_TOKEN	optional · secret	none	Operator token recording completion of privacy requests

Client registration looks like this.

export TAKOSUMI_ACCOUNTS_CLIENTS='[{"clientId":"takosumi-dashboard","redirectUris":["https://takosumi.example.com/sign-in/callback"],"tokenEndpointAuthMethod":"none"}]'

Pass upstream providers as descriptor plus secret separately. Writing a secret value into the descriptor fails startup.

export TAKOSUMI_ACCOUNTS_UPSTREAM_PROVIDERS='[{"providerId":"company-sso","label":"Company SSO","issuer":"https://id.example.com","authorizationEndpoint":"https://id.example.com/oauth/authorize","tokenEndpoint":"https://id.example.com/oauth/token","userInfoEndpoint":"https://id.example.com/oauth/userinfo","clientId":"accounts-client","clientSecretEnv":"COMPANY_SSO_CLIENT_SECRET","redirectUri":"https://takosumi.example.com/sign-in/callback","scopes":["openid","profile","email"]}]'
export COMPANY_SSO_CLIENT_SECRET="<upstream client secret>"

providerId is a display/identification name; it does not change behavior. You can list any number of providers.

Runs and the runner

Variable	Required	Default	What it sets
TAKOSUMI_ENABLED_RUNNER_PROFILES	optional	opentofu-default	Comma-separated ids of enabled run profiles. Empty keeps only the default
TAKOSUMI_DEFAULT_RUNNER_PROFILE_ID	optional	opentofu-default	Profile used when a request does not specify one. Must be enabled above
TAKOSUMI_OPENTOFU_PLUGIN_CACHE_DIR	optional	/tmp/takosumi-provider-cache in the runner container	Path reused across Runs for provider binaries. Credentials, generated roots, plans, and state never go here
TAKOSUMI_SOURCE_BUILD_CACHE_DIR	optional	none	Dependency cache location for sourceBuild. Absolute path. Its bun / npm / xdg subdirectories are passed to Bun and npm
TAKOSUMI_RUNNER_KEEPALIVE_SECONDS	optional	0	How long a finished Run container stays alive. Max 900. Runner Durable Objects are per-Run, so it is not reused by the next Run
TAKOSUMI_SOURCE_ARCHIVE_ZSTD_LEVEL	optional	3	zstd level for SourceSnapshot archives. 1 to 19. Lower is bigger but faster on first ingest
TAKOSUMI_SCHEDULED_SOURCE_POLL_BATCH	optional	5	Auto-sync Sources picked up per poll tick
TAKOSUMI_COMPATIBILITY_CHECK_TIMEOUT_MS	optional	45000	Max time (ms) to wait for source expansion in a compatibility check request

Leaving TAKOSUMI_OPENTOFU_PLUGIN_CACHE_DIR empty makes the runner expand providers into the per-Run working area. Nothing is shared, so nothing can be mixed up between Runs.

export TAKOSUMI_ENABLED_RUNNER_PROFILES="opentofu-default"
export TAKOSUMI_OPENTOFU_PLUGIN_CACHE_DIR="/tmp/takosumi-provider-cache"

Cloudflare setups

Variable	Required	Default	What it sets
TAKOSUMI_CONTROL_D1_SCHEMA_MODE	optional	bootstrap	bootstrap prepares the schema on request. predeployed stops that and verifies the migration ledger read-only
TAKOSUMI_PRODUCTION_HARDENING_GATE	optional	observe	observe only reports gaps. enforce makes internal inspection endpoints return 503 while evidence is missing
TAKOSUMI_PLATFORM_HARDENING_EVIDENCE	required with enforce	none	Non-secret JSON answering the inspection above
TAKOSUMI_RELEASE_ACTIVATOR_URL	optional	none	Webhook URL that takes over app publication after apply
TAKOSUMI_RELEASE_ACTIVATOR_TOKEN	required when set above · secret	none	Bearer for that webhook
TAKOSUMI_RELEASE_SOURCE_BUCKET	optional	none	Bucket name for the SourceSnapshot passed to the webhook

Set these in [vars] in wrangler.toml or push them as secrets.

bunx wrangler secret put TAKOSUMI_RELEASE_ACTIVATOR_TOKEN \
  --config deploy/platform/wrangler.toml

PostgreSQL setups

Variable	Required	Default	What it sets
TAKOSUMI_ACCOUNTS_PUBLIC_HOSTNAME	required with Caddy	app.example.com	Public hostname users hit. Caddy issues the ACME certificate for it
TAKOSUMI_ACCOUNTS_BIND_HOST	optional	0.0.0.0	Address to listen on inside the container
TAKOSUMI_ACCOUNTS_PORT	optional	8787	Port to listen on. PORT wins if set
TAKOSUMI_ACCOUNTS_STATIC_DIR	optional	the dashboard build in the repo	Where the dashboard distribution lives
TAKOSUMI_ACCOUNTS_PG_POOL_MAX	optional	20	Connection pool ceiling
TAKOSUMI_ACCOUNTS_PG_IDLE_TIMEOUT_MS	optional	30000	Time before an idle connection closes
TAKOSUMI_ACCOUNTS_PG_CONNECT_TIMEOUT_MS	optional	5000	Time to wait for a connection
TAKOSUMI_ACCOUNTS_PG_STATEMENT_TIMEOUT_MS	optional	30000	Time to wait for one statement
TAKOSUMI_ACCOUNTS_PG_SSL_MODE	optional	disable	disable / require / verify-ca / verify-full
TAKOSUMI_ACCOUNTS_PG_SSL_ROOT_CERT	required with verify-ca / verify-full	none	PEM CA bundle
POSTGRES_PASSWORD	required with compose · secret	none	Password the bundled compose sets on PostgreSQL

The bundled compose reads these from deploy/node-postgres/.env.

cat >> deploy/node-postgres/.env <<'ENV'
TAKOSUMI_ACCOUNTS_PUBLIC_HOSTNAME=takosumi.example.com
TAKOSUMI_ACCOUNTS_PG_SSL_MODE=require
ENV

What the CLI reads

Variable	Required	Default	What it sets
TAKOSUMI_DEPLOY_CONTROL_URL	required when --url is omitted	none	The Takosumi origin the CLI talks to
TAKOSUMI_DEPLOY_CONTROL_TOKEN	required when --token is omitted · secret	none	Bearer for that origin
TAKOSUMI_ACCOUNTS_URL	required when --accounts-url is omitted	none	Accounts URL used by takosumi accounts tokens
TAKOSUMI_ACCOUNTS_DATABASE_URL	required when --database-url is omitted	none	Connection used by takosumi accounts migrate
TAKOSUMI_LANG	optional	from LANG etc.	A value starting with ja makes CLI help Japanese. TAKOSUMI_LOCALE is read too

export TAKOSUMI_DEPLOY_CONTROL_URL=https://takosumi.example.com
export TAKOSUMI_DEPLOY_CONTROL_TOKEN="$(cat ~/.config/takosumi/token)"
takosumi connections list

Related

• Run it yourself
• CLI
• Product boundaries