Configuration

TinyCloud node config comes from built-in defaults, tinycloud.toml, and TINYCLOUD_ environment variables. Canonical nested env vars use double underscores.

Canonical examples

TINYCLOUD_STORAGE__DATABASE="sqlite:./data/caps.db"
TINYCLOUD_STORAGE__BLOCKS__TYPE="Local"
TINYCLOUD_STORAGE__BLOCKS__PATH="./data/blocks"
TINYCLOUD_KEYS__SECRET="base64url-secret"
TINYCLOUD_PROMETHEUS__PORT=8001
TINYCLOUD_TELEMETRY__ENABLED=true

Core keys

TOML key	Purpose	Default
`port`	HTTP API port	`8000`
`address`	Bind address	`127.0.0.1`
`cors`	Enable CORS headers	`false`
`storage.datadir`	Root directory for local data	`./data`
`storage.database`	SQL database connection string	`sqlite:./data/caps.db`
`storage.blocks.type`	Block backend	`Local`
`storage.staging.type`	Staging backend	`Memory`
`prometheus.port`	Metrics port	`8001`
`telemetry.enabled`	Start the metrics server	`false`
`log.format`	Log format	`Text`
`log.tracing.enabled`	Enable OTLP tracing	`false`

Storage layout

If you leave local paths unset, the node resolves them under storage.datadir:

caps.db for the SQL database
blocks/ for local block storage
sql/ and duckdb/ for database artifacts

Keys

The node requires a static secret for key derivation unless you are using a specialized deployment mode.

openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

Set the URL-safe, unpadded result in TINYCLOUD_KEYS__SECRET.

Logging and tracing

Use [log] for log format and tracing settings:

[log]
format = "Json"

[log.tracing]
enabled = true

When tracing is enabled, the node builds an OTLP gRPC exporter using the exporter’s default endpoint. The current TinyCloud config exposes the enable flag and trace-header name, but not a collector-endpoint setting.

The server still accepts legacy single-underscore env vars, but canonical double-underscore env vars take precedence when both are present.

CLI

Hosting

OpenKey

Support

Canonical examples

Core keys

Storage layout

Keys

Logging and tracing

​Canonical examples

​Core keys

​Storage layout

​Keys

​Logging and tracing

Canonical examples

Core keys

Storage layout

Keys

Logging and tracing