---
title: "RUAL Core Nano · RUAL Documentation"
description: "The whole platform on one machine: SQLite instead of Elasticsearch, one box instead of a stack, and when to choose it over a cluster."
canonical: https://docs.rual.nl/architecture/core-nano
language: en
---

# RUAL Core Nano

The whole platform on one machine. RUAL Core on embedded SQLite instead of Elasticsearch, one box instead of an assembled stack, and the same blueprints you already write.

RUAL Core Nano is not a different product. It is RUAL Core configured for a single machine: one application on one box you own, or one node inside the building it automates. The document backend swaps from Elasticsearch to embedded SQLite, and a different set of blocks is enabled. Everything else is unchanged: blueprints, state pages, endpoints, the queue and auth behave exactly as they do on a cluster.

The point is latency and independence. A page render, an API call or a sensor two metres from the node should not need a round trip to servers in another country, and the application should not stop working because somebody's internet did.

### One Box Instead of a Stack

Every capability a small application needs is usually assembled from a separate service, each with its own account, its own configuration and its own model of a user. In Nano each one is part of the core:

| Capability | Typically assembled from | In Nano |
| --- | --- | --- |
| Document storage | a hosted Postgres or document service | embedded SQLite, same storage blocks |
| Search and filtering | the database, or Elasticsearch alongside it | the SQLite engine, see the search note below |
| Auth, sessions, tokens | an auth SaaS, or the database's auth add-on | built in: users, roles, scopes, tokens |
| File storage | object storage, or the vendor's storage add-on | the asset store, on the same disk |
| HTTP endpoints | serverless functions on a host | blueprint endpoints |
| Background work | a queue service or a worker process | the built-in queue |
| Scheduled work | a cron service | repeating events |
| Frontend | a separately hosted frontend app | state pages and custom React components |
| Deploys | a git-connected build pipeline | the deployment flow |
| Backups | configured per service, separately | one SQLite file and one asset directory |

What that buys is mostly the absence of seams. There is one process to run, one configuration file and one restore path. Nothing needs wiring between services that each keep their own model of a user, because users, data and endpoints already live in one place. The resource footprint is fixed and sits on hardware you own, rather than being metered per invocation. And the node keeps working with the internet down.

What you give up, stated just as plainly: there is no CDN or edge presence, so pages are served from wherever the machine sits. There is no autoscaling: the machine is the capacity. One machine is one point of failure. And SQLite search differs from Elasticsearch exactly where search gets hard: free text. The limits section below has the details.

### When to Choose Nano Over a Cluster

| Situation | Choose |
| --- | --- |
| One application on one machine, or one building to run | **Nano** |
| Data stays on premises, or the thing must keep working with the internet down | **Nano** |
| A public service with users everywhere | **Cluster** |
| Load that spikes, or grows past what one machine serves | **Cluster** |
| Uptime that must survive a single machine failing | **Cluster** |

Both shapes run the same blueprints, so starting on a Nano does not paint you into a corner. The growth path is below.

### Minimum Specifications

These are the numbers to buy against, not the numbers where it technically boots.

| Component | Minimum | Recommended | Why this number |
| --- | --- | --- | --- |
| CPU | 4 cores, ARM64 or x86-64 | Apple M2 / M4, or a modern 6-core x86 | Blueprint execution is the load, and it is bursty rather than sustained. Four cores keeps the queue workers and a page render from contending, with room left for whatever runs beside the core. |
| RAM | **8 GB** | **16 GB** | The core itself sits around 300–500 MB. What consumes the rest is everything beside it: SQLite in WAL mode wants page cache, and Redis holds the hot document cache. 8 GB runs the node on its own; 16 GB is the comfortable number once local home automation adds its daemons, or the geo datasets are loaded. |
| Storage | 128 GB SSD | 512 GB SSD | SSD is not negotiable: SQLite's write path is fsync-bound, and on spinning or SD-card storage that is the difference between a responsive node and a visibly slow one. SD cards additionally wear out under WAL churn. |
| Network | Wired Ethernet | Wired Ethernet | The node is a server: clients, integrations and any local devices all reach it over the network. A server on WiFi puts a retry loop between every request and its destination. |
| Power |  | Small UPS | A node that loses power mid-write does not always come back cleanly. A small UPS is the difference between a clean shutdown and a fsck. |

USB only matters once radios are attached for local home automation; the [tutorial](https://docs.rual.nl/tutorials/local-home-automation) covers ports, hubs and the extension cables.

#### Reference Builds

| Machine | Verdict |
| --- | --- |
| **Mac Mini M2, 16 GB** | The comfortable default. Silent, low power, and enough headroom to run the home-automation daemons in Docker alongside the node. Two USB-A ports, which matters once radios are attached. |
| **Mac Mini M4, 16 GB** | Same role, faster chip. The M4 has no USB-A ports (front USB-C, rear Thunderbolt), so radios hang off a hub; see the tutorial. |
| **Mac Mini M2, 8 GB** | Fine for the node and a modest blueprint set. Tight once you add home-automation daemons. |
| **Intel NUC / mini-PC, 16 GB, NVMe** | Equivalent, usually cheaper, usually louder. |
| **Raspberry Pi 5, 8 GB, NVMe HAT** | Workable for a small installation. Use NVMe, not an SD card. Expect page renders to be noticeably slower. |
| **Raspberry Pi 4 or any SD-card-only board** | Don't. The SD card is the problem, not the CPU. |

### Configuration

Start from `configs/nano.example.toml` in the RUAL Core repository. The section that makes a Nano a Nano:

```toml
[general]
storage_engine = "sqlite"
active_entities = [1]
file_path = "/var/lib/rual"
```

`storage_engine = "sqlite"` is the whole switch; every other key means what it means on any deployment. Home automation is off by default and configured separately: see [Local Home Automation](https://docs.rual.nl/tutorials/local-home-automation).

### What to Know Before You Commit

- **SQLite search is close to Elasticsearch, not identical.** Structured queries are exact; free text is a substring match rather than an analyzed one, and nothing is scored. For a search-heavy application, test the real queries against a Nano before committing to the shape.

- **Test the restore, not the backup.** The state that matters is one SQLite file and one asset directory, which makes the backup a single job. Rehearse putting it back onto a fresh machine once, before the box matters.

- **Upgrades are not rolling.** There is one process, so a core upgrade is a restart with a short window of downtime. The routine itself is the same as on a cluster: see [Version Management](https://docs.rual.nl/architecture/version-guide).

### Moving to a Cluster Later

A Nano is not a dead end. The application layer is identical on both shapes: blueprints, state pages, endpoints and users carry over, because only the storage engine differs. The move is a data job, not a rebuild: stand up the cluster, move the documents and assets across, repoint the URL and deploy the same blueprints. The behaviour worth re-testing afterwards is search, which gains analyzed, scored matching on the cluster and will not behave exactly as SQLite did.

### Home Automation

One more reason to pick this shape: a Nano can automate the building it sits in. Zigbee, Thread/Matter, Z-Wave, Philips Hue and Daikin devices are adopted into the same document model and driven by the same blueprint blocks, locally, with no vendor cloud in the loop. It is off by default and costs nothing when disabled. The radios, the daemon stack and the blocks are their own tutorial: [Local Home Automation](https://docs.rual.nl/tutorials/local-home-automation).

### Next Steps