TinyCloud node config comes from built-in defaults, tinycloud.toml, and TINYCLOUD_ environment variables. Canonical nested env vars use double underscores.
Canonical examples
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 databaseblocks/ for local block storagesql/ and duckdb/ for database artifacts
Keys
The node requires a static secret for key derivation unless you are using a specialized deployment mode.
Set the URL-safe, unpadded result in TINYCLOUD_KEYS__SECRET.
Logging and tracing
Use [log] for log format and tracing settings:
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.
