Skip to main content
A TinyCloud node is the server component that provides storage, authentication, and delegation services. You can run your own node for full control over your data infrastructure.

​
What is a TinyCloud Node?

A TinyCloud node handles:
  • Authentication — verifying SIWE signatures and managing sessions
  • Key-value storage — storing and retrieving user data in spaces
  • Delegations — creating, verifying, and enforcing access delegations
  • Block storage — persisting data to local filesystem or S3-compatible storage
  • Relay — connecting nodes for cross-node delegation resolution

​
System Requirements

RequirementMinimumRecommended
CPU1 core2+ cores
RAM512 MB2 GB
Disk1 GB10 GB+ (depends on usage)
RuntimeDocker or Rust toolchainDocker
NetworkPort 8000 openPorts 8000, 8001, 8081

​
Quick Start

1

Clone the repository

git clone https://github.com/TinyCloudLabs/tinycloud-node.git
cd tinycloud-node
2

Create a configuration file

Create a minimal tinycloud.toml:
port = 8000
address = "0.0.0.0"

[storage]
database = "sqlite:./data/caps.db"

[storage.blocks]
type = "Local"
path = "./data/blocks"

[keys]
type = "Static"
# Set via TINYCLOUD_KEYS__SECRET env var instead
Never put your secret key directly in the config file. Use the TINYCLOUD_KEYS__SECRET environment variable instead.
3

Generate a secret key

Generate a random key of at least 32 bytes, base64url-encoded:
openssl rand -base64 32
4

Run with Docker

docker run -d \
  --name tinycloud \
  -p 8000:8000 \
  -e TINYCLOUD_KEYS__SECRET=<your-base64url-secret> \
  -v ./data:/data \
  ghcr.io/tinycloudlabs/tinycloud-node
5

Verify it's running

curl http://localhost:8000/healthz
You should see a 200 OK response.

​
Ports

PortServiceDescription
8000APIMain HTTP API for clients
8001PrometheusMetrics endpoint
8081RelayNode-to-node relay protocol

​
Docker Image

The official Docker image is available on GitHub Container Registry: 
ghcr.io/tinycloudlabs/tinycloud-node
See the Docker deployment guide for full Docker and Docker Compose instructions.

​
What’s Next

Configuration

Full configuration reference for tinycloud.toml

Docker Deployment

Deploy with Docker and Docker Compose

Database Setup

Configure SQLite, PostgreSQL, or MySQL

Monitoring

Health checks, metrics, and observability

​
Source Code

GitHub Repository

tinycloud-node on GitHub