- C# 96.3%
- Shell 3.6%
- Dockerfile 0.1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .forgejo/workflows | ||
| docs | ||
| libs | ||
| scripts | ||
| src | ||
| tests | ||
| .dockerignore | ||
| .gitignore | ||
| .gitmodules | ||
| Architecture.md | ||
| CHANGELOG.md | ||
| CLA.md | ||
| compose.yaml | ||
| CONTRIBUTING.md | ||
| Dockerfile | ||
| LICENSE | ||
| README.md | ||
| unilayer.slnx | ||
unilayer
A modular REST API interface designed to provide secure, scalable, and maintainable access to Collections (database tables), Assets (files), and Users (the clients of the API – apps, services, scripts – with their roles and permissions). Acts as an intermediary layer between client applications and backend systems (database, storage, cache).
Features
- Dynamic Collections: Create and manage database tables at runtime via REST API
- Asset Management: Upload, store, and retrieve files with configurable storage backends
- API Users: One per app or service, not the end users of your app (no sign-up, login or password); role-based access control, every user has an opaque bearer token, next to a static token for the operator
- Permission System: String-based permissions with policy and role management via REST API
- Caching: Built-in Valkey support for performance optimization
- Multi-backend Support: PostgreSQL, Valkey, files through the storage service (or local / S3-compatible storage)
- GraphQL next to REST, and a cluster mode (Raft) for several nodes
Documentation
Requirements
- .NET 10.0 SDK
- PostgreSQL 14+
- Valkey (Redis-compatible) 7.0+
- Optional: MinIO or S3-compatible storage for cloud storage
Installation
PostgreSQL
macOS (Homebrew):
brew install postgresql@16
brew services start postgresql@16
Ubuntu/Debian:
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql
Windows (Chocolatey):
choco install postgresql16
Create a database and user:
CREATE DATABASE unilayer;
CREATE USER unilayer_user WITH PASSWORD 'your_secure_password';
GRANT ALL PRIVILEGES ON DATABASE unilayer TO unilayer_user;
Valkey
macOS (Homebrew):
brew install valkey
brew services start valkey
Ubuntu/Debian:
sudo apt update
sudo apt install valkey-server
sudo systemctl start valkey-server
sudo systemctl enable valkey-server
Windows: Download from Valkey releases and run as service.
Docker:
docker run -d --name valkey -p 6379:6379 -v valkey-data:/data valkey/valkey
MinIO (Optional - for S3 storage)
Docker:
docker run -d -p 9000:9000 -p 9001:9001 minio/minio server /data --console-address ":9001"
Access the MinIO console at http://localhost:9001 (default credentials: minioadmin/minioadmin).
Configuration
Create an appsettings.yaml file in the project root:
# Server configuration
endpoint: "0.0.0.0:5380"
# Authentication
authentication:
staticApiToken: "your-secure-api-token"
# Database configuration (PostgreSQL example)
database:
connectionString: "Host=localhost;Database=unilayer;Username=unilayer_user;Password=your_secure_password;Port=5432"
# Valkey configuration
valkey:
host: "localhost"
port: 6379
password: ""
database: 0
keyPrefix: "unilayer:"
# Storage configuration (Local filesystem)
storage:
provider: "local"
local:
path: "./storage/assets"
# Alternative: MinIO/S3 storage
# storage:
# provider: "minio"
# s3:
# endpoint: "http://localhost:9000"
# accessKey: "minioadmin"
# secretKey: "minioadmin"
# bucketName: "unilayer-assets"
# useSsl: false # unset: HTTPS unless the endpoint is local
# createBucketIfNotExists: true
Configuration Options:
| Component | Config Path | Description |
|---|---|---|
| Database | database:startupWaitSeconds |
How long the start waits for a database server that does not take connections yet (default 60; 0 ends at once). |
| Database | database:connectionString |
Connection string for the database. Leave Max Auto Prepare unset: the collections are read with SELECT *, and a statement prepared before a schema change fails afterwards (0A000); measured, it gained nothing. |
| Valkey | valkey:host |
Valkey server hostname |
| Valkey | valkey:port |
Valkey server port |
| Valkey | valkey:password |
Valkey authentication password |
| Valkey | valkey:user (UNILAYER_VALKEY_USER) |
ACL user of the connections, when not the default user |
| Cache | cache:host (UNILAYER_CACHE_HOST) |
A second Valkey that only caches; valkey:* then keeps the volatile collections alone. Optional for one node, needed by every node of a cluster. Also cache:port, cache:password, cache:user, cache:database, cache:ssl |
| Valkey | valkey:maxValueLength (UNILAYER_VALKEY_MAXVALUELENGTH) |
The longest value cached, in characters (default 2 MiB); a longer one - a large page with its references - is read from the database each time. /metrics counts hits, misses, errors and values too large in unilayer_cache_operations_total. |
| Valkey | valkey:database |
Valkey database number (default 0) |
| Valkey | valkey:keyPrefix (UNILAYER_VALKEY_KEYPREFIX) |
Prefix of every key the server writes, unilayer: by default; give each instance sharing a Valkey its own. The storage service writes under unilayer-storage:. |
| Collections | collections:cacheTtlMinutes (5), collections:maxPageSize (1000), collections:maxBulkItems (1000) |
How long lists and items stay cached, the largest page, the most items of one bulk write |
| Collections | collections:autoCreateTables (true) |
Whether a write to a missing collection creates it, and whether collections can be created at all |
| Users | users:cacheTtlMinutes (5), users:defaultRole (user) |
Cache lifetime of users, the role of a user created without one |
| Permissions | permissions:cacheTtlMinutes (5) |
How long a role's permission set stays cached in Valkey |
| Audit | audit:enabled (true) |
Whether security-relevant actions are written to systemauditlogs |
| Assets | assets:maxFileSizeBytes (100 MiB), assets:maxCachedContentBytes (1 MiB), assets:metadataCacheTtlMinutes / assets:contentCacheTtlMinutes (5) |
The largest upload, the largest content kept in the cache, and how long metadata and content stay there |
| Storage | storage:provider |
service (the default: the storage service, storage:service:url required), local or minio/s3 (content through the API, on their way out) or none - see docs/Assets.md |
| Storage | storage:quotaBytes (UNILAYER_STORAGE_QUOTABYTES) |
The most all assets may take together; 0 (default) for no limit. An upload or a restore beyond it is refused with 507 STORAGE_QUOTA_EXCEEDED. Deleted assets don't count until they are purged (assets:retention:*, see docs/Assets.md). /metrics reports unilayer_assets_size_bytes and unilayer_assets_quota_bytes. |
| Local Storage | local:path |
Base directory for file storage |
| MinIO/S3 | s3:endpoint |
MinIO/S3 endpoint URL |
| MinIO/S3 | s3:accessKey |
Access key for authentication |
| MinIO/S3 | s3:secretKey |
Secret key for authentication |
| MinIO/S3 | s3:bucketName |
Bucket name for storage |
| Authentication | authentication:staticApiTokenSecondary |
A second static token accepted next to staticApiToken, for rotating it (see Authentication) |
| TLS | tls:certificatePath / tls:certificatePassword |
Server certificate (PKCS#12) of the API; with it the API is served over HTTPS |
| TLS | tls:reloadIntervalSeconds |
How often the certificate files are checked for a renewal (default 30; 0: never, a renewal needs a restart) |
| Metrics | metrics:endpoint |
ip:port of a separate listener serving /metrics (Prometheus); empty: off (see Metrics) |
| Network | network:knownProxies (UNILAYER_NETWORK_KNOWNPROXIES) |
Reverse proxies in front of the API, comma-separated addresses or networks (10.0.0.0/8): their X-Forwarded-For names the client, so rate limits and the sign-in throttle count per client; empty: the header is ignored |
| Rate limits | rateLimit:globalPerMinute (1000), rateLimit:writesPerMinute (50) |
Requests and writes per client and minute. They are counted on each node: behind a load balancer over several nodes a client gets up to that many per node |
| Idempotency | idempotency:enabled / idempotency:retentionHours |
The Idempotency-Key header (default on) and how long keys are remembered (default 24) |
| Compression | compression:enabled (UNILAYER_COMPRESSION_ENABLED) |
Brotli/gzip compression of JSON and other text responses (default on). Set to false when a reverse proxy compresses |
| Compression | compression:level (UNILAYER_COMPRESSION_LEVEL) |
fastest (default), optimal or smallest |
| Compression | compression:mimeTypes (UNILAYER_COMPRESSION_MIMETYPES) |
Comma-separated MIME types that replace the default list of text-like types |
Quick Start
docker compose up -d runs PostgreSQL, Valkey, the API and the storage service together (see compose.yaml). To run the API from source:
- Clone with submodules (
git clone --recurse-submodules, orgit submodule update --initin an existing clone): the client and the shared models come fromlibs/client, the storage service fromlibs/storage - Install dependencies (PostgreSQL, Valkey)
- Create
appsettings.yamlwith your configuration - Run database migrations (automatic on startup)
- Start the API:
dotnet run --project src/unilayer
The API listens on http://localhost:5380; the API reference (Scalar) is at http://localhost:5380/api/v1, the OpenAPI document at /api/v1/openapi/v1.json.
Docker
docker compose up -d is the way to run it (see Quick Start). The image is built from a published server - the
Dockerfile copies publish/, it doesn't compile:
dotnet publish src/unilayer -c Release -r linux-x64 --self-contained false -o publish
docker build -t unilayer .
The container needs at least a database and Valkey: UNILAYER_DATABASE_CONNECTIONSTRING, UNILAYER_VALKEY_HOST
(and UNILAYER_VALKEY_PASSWORD), and UNILAYER_AUTHENTICATION_STATICAPITOKEN for the first sign-in. Its liveness and
readiness are /health/live and /health/ready.
API Overview
Base URL: /api/v1
| Endpoint | Method | Description | Required Permission |
|---|---|---|---|
/collections |
GET | List all collections | collections:read |
/collections/{name} |
GET | Get all items in a collection | collections:read, collections:{scope}:read or collections:{scope}:{name}:read |
/collections/{name}/info |
GET | Get collection metadata and fields | collections:read |
/collections |
POST | Create a collection: {"name": ..., "fields": [...]} |
collections:write |
/collections/{name} |
POST | Add an item (creates the collection from it with collections:autoCreateTables) |
collections:write, collections:{scope}:write or collections:{scope}:{name}:write |
/collections/{name}/count |
GET | Count the items, optionally matching ?filter= |
collections:read, collections:{scope}:read or collections:{scope}:{name}:read |
/collections/{name}/bulk |
POST | Add up to 1,000 items in one transaction (one write against the rate limit) | collections:write, collections:{scope}:write or collections:{scope}:{name}:write |
/collections/{name}/bulk |
PUT | Update up to 1,000 items in one transaction: {"ids": [...], "entities": [...]} |
collections:write, collections:{scope}:write or collections:{scope}:{name}:write |
/collections/{name}/bulk/delete |
POST | Delete up to 1,000 items by id; returns how many were deleted | collections:write, collections:{scope}:write or collections:{scope}:{name}:write |
/assets |
GET | List all assets | assets:read |
/assets/{uid} |
GET | Download an asset (optional image modifiers) | assets:read |
/assets |
POST | Upload an asset | assets:write |
/assets/{uid}/upload-session, .../complete |
POST | Upload content through the storage service (see docs/Assets.md) | assets:write |
/assets/{uid}/download-url |
GET | A download URL of the storage service | assets:read |
/storage/keys |
GET | The public key the storage service checks tokens with | none |
/users |
GET | List all users | users:read |
/users |
POST | Create a new user | users:write |
/users/{id} |
GET | Get a specific user | users:read |
/users/{id} |
DELETE | Delete a user | users:write |
/users/{id}/role |
PUT | Update a user's role | users:write |
/roles |
GET | List all roles | security:read |
/roles |
POST | Create a new role | security:write |
/roles/{nameOrId} |
GET | Get a specific role | security:read |
/roles/{roleId} |
PUT | Update a role | security:write |
/roles/{roleId} |
DELETE | Delete a role | security:write |
/roles/{roleId}/policies/{policyId} |
POST | Assign policy to role | security:write |
/roles/{roleId}/policies/{policyId} |
DELETE | Remove policy from role | security:write |
/policies |
GET | List all policies | security:read |
/policies |
POST | Create a new policy | security:write |
/policies/{nameOrId} |
GET | Get a specific policy | security:read |
/policies/{policyId} |
PUT | Update a policy | security:write |
/policies/{policyId} |
DELETE | Delete a policy | security:write |
/policies/{policyId}/permissions/{permission} |
POST | Add permission to policy | security:write |
/policies/{policyId}/permissions/{permission} |
DELETE | Remove permission from policy | security:write |
See the full API documentation for detailed endpoint specifications.
Query Parameters
The collections list endpoint supports the following query parameters:
| Parameter | Type | Description |
|---|---|---|
limit |
integer | Maximum number of items to return (default: 100) |
offset |
integer | Number of items to skip (default: 0) |
fields |
string | Comma-separated list of fields to include |
sort |
string | Sort order for results |
filter |
string | Filter expression |
Sort Parameter:
- No sort: Orders by
unilayer_indexASC (insertion order) sort=asc: Orders byunilayer_indexASCsort=desc: Orders byunilayer_indexDESCsort=fieldname: Orders byfieldnameASCsort=fieldname:asc: Orders byfieldnameASCsort=fieldname:desc: Orders byfieldnameDESCsort=field1,field2:desc: Orders byfield1ASC,field2DESC
Response Format
All collection item responses are wrapped with system metadata separated from user data to prevent field name collisions.
Single Item Response
{
"data": {
"name": "Test Item",
"description": "A test item"
},
"metadata": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"index": 1,
"createdAt": "2024-01-01T10:00:00Z",
"updatedAt": null
}
}
Multiple Items Response
{
"data": [
{"name": "Item 1", "description": "First item"},
{"name": "Item 2", "description": "Second item"}
],
"metadata": {
"count": 2,
"limit": 100,
"offset": 0,
"has_more": false
}
}
Collection Info Response
{
"name": "mycollection",
"tableName": "unilayer_mycollection",
"createdAt": "2024-01-01T10:00:00Z",
"updatedAt": null,
"isSystem": false,
"fields": [
{"name": "name", "type": "TEXT", "nullable": false},
{"name": "description", "type": "TEXT", "nullable": true}
],
"systemFields": [
{"name": "unilayer_id", "columnName": "unilayer_id", "type": "UUID", "isPrimaryKey": true, "isNullable": false},
{"name": "unilayer_index", "columnName": "unilayer_index", "type": "BIGSERIAL", "isPrimaryKey": false, "isNullable": false},
{"name": "unilayer_created_at", "columnName": "unilayer_created_at", "type": "TIMESTAMP", "isPrimaryKey": false, "isNullable": false},
{"name": "unilayer_updated_at", "columnName": "unilayer_updated_at", "type": "TIMESTAMP", "isPrimaryKey": false, "isNullable": true}
]
}
Note: System fields (
unilayer_id,unilayer_index,unilayer_created_at,unilayer_updated_at) are automatically managed by unilayer and cannot be defined by users. Field names starting withunilayer_are reserved.
Authentication
Authentication uses Bearer tokens. Include the token in the Authorization header:
Authorization: Bearer your-secure-api-token
Rotating the static token
authentication:staticApiTokenSecondary (UNILAYER_AUTHENTICATION_STATICAPITOKENSECONDARY) is a second static token
that is accepted next to authentication:staticApiToken. To replace the token without downtime: set the new token as
the secondary one and restart, switch the clients to it, then make it the primary token, clear the secondary one and
restart again. Both tokens give the admin role; both may be configured in plaintext or hashed.
The root user follows the primary token: at every start it is keyed to authentication:staticApiToken, so the old
token stops working with that last restart - also in a database that was restored from the backup of another instance,
whose root user arrives with that instance's token.
Retrying writes safely: Idempotency-Key
Send any unique string (e.g. a UUID) in the Idempotency-Key header of a POST, PUT, PATCH or DELETE, and the
request may be retried - after a timeout, a dropped connection, a 503 - without being applied twice:
- the first request runs and its response is remembered for
idempotency:retentionHours(default 24); - a retry with the same key gets that response again, with the header
Idempotent-Replay: true, and nothing is written; - a retry with the same key but another body gets
422: a key stands for one request, not for its route; - a second request with the same key while the first is still running gets
409; - a response with a 5xx status is not remembered: the retry runs again.
A key belongs to the caller, the method and the path; the same key from another user or on another route is another
request. Responses larger than idempotency:maxResponseBytes (default 64 KB) are replayed with their status and
without the body. In cluster mode the keys are part of the replicated data, so a retry is recognized by whichever node
is the leader by then (see docs/Cluster.md, Consistency).
Metrics
With metrics:endpoint (UNILAYER_METRICS_ENDPOINT, e.g. 0.0.0.0:9464) the server opens a second listener that
serves /metrics in the Prometheus text format and nothing else. It is plain HTTP without authentication: keep it
inside the network of your monitoring system. The API port never serves the metrics.
| Metric | Meaning |
|---|---|
unilayer_http_requests_total{method,status} |
Requests served, by method and status class (2xx, ...) |
unilayer_http_request_duration_seconds{method} |
Histogram of the request duration |
unilayer_database_size_bytes |
Size of the PostgreSQL database (read at most once a minute) |
unilayer_assets_optimized_total, _optimize_skipped_total{reason}, _optimize_failed_total |
Image versions given an optimized copy, left without one, or failed (with assets:optimize:enabled, see docs/Assets.md) |
unilayer_assets_optimize_saved_bytes_total, unilayer_assets_optimized_copies_bytes |
Bytes the copies saved, and bytes held in copies (not part of the quota) |
unilayer_assets_image_downloads_total{source} |
Downloads of JPEG/PNG/GIF assets served from the optimized copy or the original |
unilayer_assets_optimize_backfill_remaining |
Assets the running backfill pass has still to look at |
unilayer_uptime_seconds, unilayer_process_working_set_bytes, unilayer_info{version} |
The process |
unilayer_cluster_role{role} |
1 for the node's role (leader, follower, candidate) |
unilayer_cluster_has_leader |
1 while the node knows the leader; 0 means an election or a lost majority |
unilayer_cluster_term, _last_index, _commit_index, _applied_index |
The state of the replicated log |
unilayer_cluster_apply_lag_entries |
Committed entries the node has not applied yet (replication lag) |
unilayer_cluster_members, unilayer_cluster_members_available |
Members, and how many the node reached last (meaningful on the leader) |
unilayer_cluster_snapshot_age_seconds, _snapshot_index, _snapshot_size_bytes |
The node's last snapshot |
unilayer_cluster_certificate_expiry_timestamp_seconds |
When the node certificate or the cluster CA expires |
The unilayer_cluster_* series exist in cluster mode only.
Permission System
unilayer uses a string-based permission system with roles and policies:
- Policies contain a list of permission strings (e.g.,
collections:read,assets:write) - Roles are assigned one or more policies
- Users are assigned a single role
- Write permissions automatically imply read permissions (e.g.,
collections:writeincludescollections:read) - A collection's scope is the part of its name before the first underscore, its name in a permission the rest. A permission covers the levels below it:
collections:writeevery collection,collections:shop:writeevery collection of the scope,collections:shop:order_items:writethat one collection. Whoever grants permissions through policies needs each of them themselves.
Permission String Format
| Permission | Description |
|---|---|
collections:read |
Read all collections |
collections:write |
Create/update/delete all collections |
collections:{scope}:read |
Read the collections of a scope: collections:shop:read covers shop and every shop_... |
collections:{scope}:write |
Write the collections of a scope |
collections:{scope}:{name}:read |
Read one collection: collections:shop:order_items:read is shop_order_items |
collections:{scope}:{name}:write |
Write one collection |
assets:read |
Read all assets |
assets:write |
Create/update/delete all assets |
assets:purge |
Remove deleted assets for good (DELETE /assets/{uid}?purge=true) |
users:read |
Read all users |
users:write |
Create/update/delete all users |
security:read |
Read all roles and policies |
security:write |
Create/modify/delete roles and policies |
Built-in Immutable Entities
On first startup, unilayer automatically creates:
fullaccesspolicy - Contains all permissions (collections:read,collections:write,assets:read,assets:write,assets:purge,users:read,users:write,security:read,security:write,cluster:admin); a permission added in a later version is added to it at the next startadminrole - Assigned thefullaccesspolicy, immutablerootuser - Created from the static API token in configuration, assigned theadminrole
Note: While a static API token is configured, the root user's token is that token: unilayer checks it at every start and re-keys the root user when it differs (a rotated token, a database restored from another instance). A token renewed for the root user through the API therefore only lasts until the next start. Without a configured static token the root user keeps the token stored in the database.
Default Roles
admin- Full access to all system resources (immutable)user- Default role for new users (configurable)
API Examples
Authentication
All requests require a valid Bearer token:
# Using the root user token (from initial configuration)
ROOT_TOKEN="your-initial-static-token"
# Or use a token from a created user
USER_TOKEN="user-specific-token"
curl -H "Authorization: Bearer $ROOT_TOKEN" \
http://localhost:5380/api/v1/users
Creating a New User
curl -X POST \
-H "Authorization: Bearer $ROOT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"username": "john", "role": "user"}' \
http://localhost:5380/api/v1/users
Response:
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"username": "john",
"role": "user",
"apiToken": "generated-token-for-john",
"createdAt": "2026-08-30T20:00:00Z"
}
Creating a New Policy
curl -X POST \
-H "Authorization: Bearer $ROOT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "read-only",
"description": "Read-only access to collections and assets",
"permissions": [
"collections:read",
"assets:read"
]
}' \
http://localhost:5380/api/v1/policies
Response:
{
"id": "12345678-1234-5678-1234-567812345678",
"name": "read-only",
"description": "Read-only access to collections and assets",
"createdAt": "2026-08-30T20:00:00Z",
"isImmutable": false,
"permissions": ["collections:read", "assets:read"]
}
Creating a New Role
curl -X POST \
-H "Authorization: Bearer $ROOT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "viewer",
"description": "View-only role"
}' \
http://localhost:5380/api/v1/roles
Response:
{
"id": "87654321-4321-8765-4321-876543218765",
"name": "viewer",
"description": "View-only role",
"createdAt": "2026-08-30T20:00:00Z",
"isImmutable": false,
"policies": []
}
Assigning a Policy to a Role
# Get the policy ID and role ID first
POLICY_ID="12345678-1234-5678-1234-567812345678"
ROLE_ID="87654321-4321-8765-4321-876543218765"
curl -X POST \
-H "Authorization: Bearer $ROOT_TOKEN" \
http://localhost:5380/api/v1/roles/$ROLE_ID/policies/$POLICY_ID
Adding a Permission to a Policy
POLICY_ID="12345678-1234-5678-1234-567812345678"
curl -X POST \
-H "Authorization: Bearer $ROOT_TOKEN" \
http://localhost:5380/api/v1/policies/$POLICY_ID/permissions/users:read
Listing All Roles
curl -H "Authorization: Bearer $ROOT_TOKEN" \
http://localhost:5380/api/v1/roles
Response:
[
{
"id": "00000000-0000-0000-0000-000000000002",
"name": "admin",
"description": "System administrator with full access. This role is immutable.",
"createdAt": "2026-08-30T19:52:57Z",
"isImmutable": true,
"policies": ["fullaccess"]
},
{
"id": "87654321-4321-8765-4321-876543218765",
"name": "viewer",
"description": "View-only role",
"createdAt": "2026-08-30T20:00:00Z",
"isImmutable": false,
"policies": ["read-only"]
}
]
Listing All Policies
curl -H "Authorization: Bearer $ROOT_TOKEN" \
http://localhost:5380/api/v1/policies
Response:
[
{
"id": "00000000-0000-0000-0000-000000000001",
"name": "fullaccess",
"description": "Full access to all system resources, collections, assets, users, and security settings",
"createdAt": "2026-08-30T19:52:57Z",
"isImmutable": true,
"permissions": [
"collections:read",
"collections:write",
"assets:read",
"assets:write",
"users:read",
"users:write",
"security:read",
"security:write"
]
}
]
Getting Current User's Permissions
curl -H "Authorization: Bearer $ROOT_TOKEN" \
http://localhost:5380/api/v1/users/me/permissions
Response:
[
"collections:read",
"collections:write",
"assets:read",
"assets:write",
"users:read",
"users:write",
"security:read",
"security:write"
]
Maintenance commands
The server binary also runs one-off commands, then exits; unilayer --help lists them.
unilayer --truncate-all --dry-run # lists the collections it would delete
unilayer --truncate-all --yes # deletes every collection; users, permissions, history stay
unilayer --reinitialize-database --yes # drops every table; the next start sets the database up again
The destructive ones (--truncate-all, --reinitialize-database, --remove-optimized-assets) only change anything with --yes, and refuse in cluster mode except --remove-optimized-assets. For --import-history-file, pass the target's token in UNILAYER_IMPORT_TARGET_TOKEN or --import-target-token-file=<path>, not on the command line.
Supported Backends
| Component | Supported Backends |
|---|---|
| Database | PostgreSQL |
| Storage | Local Filesystem, MinIO/S3 |
| Cache | Valkey |
License
unilayer is open source. The repository uses two licenses:
| Component | Path | License |
|---|---|---|
| Server (API, cluster, GraphQL, schema) | everything not listed below | AGPL-3.0-only |
.NET client (Unilayer.Client) and shared models (Unilayer.Models) |
unilayer/client, here as libs/client/ |
MIT |
Storage service (unilayer.Storage) |
unilayer/storage, here as libs/storage/ |
AGPL-3.0-only |
Each submodule is covered by the license of its own repository; everything else is covered by the root LICENSE.
What this means in practice:
- Self-hosting unilayer is free, including for commercial use.
- The client and models can be used in any application, including closed-source and commercial ones. Using the client does not put your application under the AGPL.
- If you modify the server and let others use it over a network, e.g. by offering it as a hosted service, you must make your modified source code available to those users under the AGPL.
Commercial support is available from Talaryon Labs.
Copyright (c) 2026 Talaryon Labs.
Contributing
Contributions are welcome. See CONTRIBUTING.md.