> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinycloud.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure a TinyCloud node with TOML and environment variables

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

## Canonical examples

```bash theme={null}
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.

```bash theme={null}
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:

```toml theme={null}
[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.

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