Install the server — Recued Docs

The server is the product. It is a free program you run yourself. It runs every recipe. It holds your warehouse and your secret keys. It writes the audit record. It can run on a laptop or a home server. It can also run on a supported single-board computer, or a small VPS. A VPS is a small server you rent online. For scheduled and reactive work, choose a machine that stays on.

#The install script (start here)

This is the normal way to install. One command does it all. It fetches the signed binary for your platform. It checks the release manifest against Recued's pinned key. It checks the binary's signature and its declared SHA-256. Only then does it install. It puts recued on your path. And it sets the server to start when you log in.

On Linux or macOS, open a terminal and run:

curl -fsSL https://recued.com/install.sh | sh

On Windows, open PowerShell first. Press Start, type PowerShell, and open it. Then paste:

powershell

irm https://recued.com/install.ps1 | iex

It works on Linux and Windows on x64 or arm64. It works on macOS on Apple Silicon and Intel. The macOS builds are signed and notarized with a Developer ID. On Linux and macOS the script needs curl. It also needs jq to read the release manifest. If jq is missing, the script tries to install it, or tells you the exact command to run.

#After the script runs

The script prints what to do next. A new server has to be set up once, by pairing a client to it.

Start at login is on by default, and the script starts the server right away. So it is already running. To pair:

Run recued pair. It prints a pairing code, the server's addresses, and the pairing link.
Pair the webclient or the Browser Bridge with that code. See Pairing and devices.

Nothing can pair with the server without a code. A code lasts 15 minutes. Run recued pair again for a fresh one, or recued pair --pair-code-ttl 24h for a longer window.

If you turned start at login off, or the script could not start the server, start it yourself: run recued serve, or recued on Windows. It prints a pairing code and the webclient link. That server runs only while its window stays open.

Three things to know:

With a passphrase on the key file, the server needs RECUED_IDENTITY_PASSPHRASE at every start, or it stops. Autostart does not see your shell's variables. Sealed to the machine, it starts ready. See "Protecting the key file" below.
On macOS, Windows, and a Linux desktop, start-at-login is set up for your user. No root is needed. Headless Linux needs root for a boot unit, so run the script with sudo there. Without root, a headless install sets up no autostart, and says so, rather than writing a unit that would fail on every boot.
On macOS, never run the script with sudo. The server has to run as you. Run as root, it keeps its own realm, and a pairing code from your account never reaches it. The script refuses sudo on macOS. When you cannot write to /usr/local, it installs into ~/.local/lib/recued and ~/.local/bin instead, and adds that folder to your PATH for new terminals.

#Script options

Put any of these just before sh, like this: curl -fsSL https://recued.com/install.sh | RECUED_AUTOSTART=0 sh. Put it before curl instead, and only curl sees it. The script then runs without it. In PowerShell, run $env:RECUED_AUTOSTART=0 on its own line first.

Option	What it does
`RECUED_AUTOSTART=0`	Do not start at login. Then the server runs only while you run it. An update cannot restart it for you
`RECUED_PREFIX` / `RECUED_BINDIR`	Where the program files and the `recued` command go. The defaults are `/usr/local/lib/recued` and `/usr/local/bin`. On macOS, when you cannot write those, the defaults are `~/.local/lib/recued` and `~/.local/bin`. On Linux, set both to install without `sudo`. On Windows the default is `%LOCALAPPDATA%\recued\bin`
`RECUED_NO_MODIFY_PATH=1`	Do not add the command's folder to your shell's profile. By default, when that folder is not on your PATH, the script adds it for new terminals
`RECUED_CHANNEL=edge`	Follow the edge channel instead of stable
`RECUED_FORCE=1`	Install again, even when you already have the released version

Run the script again at any time. It updates a server that is behind. It repairs a broken install. On a server that is already current, it changes nothing unless you pass RECUED_FORCE=1. It does not restart a server that is running. It prints the restart command for your system instead. To uninstall, stop the running server first. The script prints the exact commands for that too.

#Other ways to install

The script is the normal path. The other paths are for contributors, and for people who want to download by hand. Get the server from the current release page. Take the signed binary. Is there no verified file for your platform? Then you cannot get that release channel there. Do not skip the signature check.

Path	Best for	Update owner
Install script	Most people. A Mac, Windows, or Linux machine you look after	The script installs and updates. The server can also stage signed releases on its chosen channel
Binary, by hand	The same machines, when you cannot run the script	The server can stage signed releases on its chosen channel
From source	Contributors and custom builds	You rebuild. The server only reports that a release exists

All paths run the same server. The choice changes how it is packed and updated. It does not change how recipes behave. It does not change how grants work, or where your data lives. See Updates for channels, and for how a server applies a release safely.

#Binary, by hand

The install script does all of this for you. Do it by hand only when you cannot run the script. Download the file for your operating system and CPU from the signed release. The installer checks three things. It checks the release manifest. It checks the binary's signature. It checks the declared SHA-256. After that it puts recued on your path. If a check fails, the installer stops. Do not go on.

To keep a foreground server and its data together while you test:

mkdir -p ./recued-data
recued serve --db ./recued-data/recued.db

The start-up banner shows the real database path. It shows the local URL. And it shows the first pairing code. For an always-on install, run the same command under your system's service manager. Do not rely on an open terminal window.

#From source

You can build the same server from a source checkout. You need Node.js 24 and npm:

npm install
npm --workspace @recued/server run build
mkdir -p ./recued-data
node backend/server/dist/bin.js serve --db ./recued-data/recued.db

On Windows, run them in PowerShell. Type npm.cmd each time the block says npm. By default, PowerShell blocks the script a plain npm runs. The mkdir and node lines work as they are.

Run those commands from the top folder of the checkout. Source builds use the source update channel. They can tell you a newer release exists. They never replace your build by themselves.

#The data directory

All the server knows lives in its data directory. That means the warehouse database and the files stored by content hash. It also means the connection records and the installed recipes. And it means the update ledger and the audit history. Treat that directory as who the server is:

Put it on storage that survives a restart or an upgrade.
Let only the account that runs Recued use it. It holds encrypted secrets and working details. That is true even after encryption at rest is on.
Back it up like anything you cannot download again. There is no hosted Recued copy to restore from.
Keep the recovery key from the first pairing away from the machine. The server unlocks with its local key file. The recovery key is the other way back into the same encrypted state.

The backup we support is the one-file encrypted archive. Read Backup and restore. Copying a live database directory is not the same as an archive. It only works if your platform can take a snapshot all at once.

#Protecting the key file

The key file sits in the data directory. So decide what protects it before the first start. The server seals it with the first factor it can find:

Factor	When it applies	Where the secret lives
`RECUED_IDENTITY_PASSPHRASE`	You set the variable	Your environment or a secret manager
A platform secret store	The macOS login keychain, Windows DPAPI, or systemd-creds can hold a secret for this host	The platform store, outside the data directory
Unsealed	Neither of the above can be used	Nothing. The key file can be read right next to the database

Set the passphrase before you start the server for the first time:

export RECUED_IDENTITY_PASSPHRASE='a long, random passphrase'
recued serve --db ./recued-data/recued.db

Keep it in the thing that starts the server. That could be a systemd EnvironmentFile, a compose env_file, or a secret manager. Do not put it in the config file. That file lives in the very directory the passphrase protects. Once a key file is sealed with a passphrase, the server needs the passphrase at every start. With no passphrase, the server stops with a clear error. It does not start without it.

#Changing the passphrase

Changing the passphrase later is cheap. Stop the server and run:

recued rotate-passphrase --db ./recued-data/recued.db

It seals the same key file again under the new passphrase. The realm, the data, and the server identity stay the same. Nothing has to pair again. Put the new value in the service's environment before you start the server.

#Changing the sealing factor

Changing which factor seals the key file is a bigger deal. That choice is saved when the file is made. It stays that way for good, for that realm.

Before the first pairing, the key file is throwaway. Changing your mind costs a fresh identity and nothing more. Stop the server. Delete the key file. Set or unset the variable. Start again.

After the first pairing, it costs more. You must make the server identity again. That takes recued recover-keyfile and your recovery key. Then every paired device must pair again. The publisher identity changes. The account binding is lost. The data itself is not touched.

An unsealed server still works. Its warehouse is still encrypted. Sealing adds one thing. A copy of the whole data directory does not carry the key that opens it. To see which factor is in use, open the webclient: Settings, then Server, then Key Health.

#Confirm health

recued status should say the server is running. If it says stopped and a start failed, it also shows that start's error. A key file sealed with a passphrase, where the server cannot see RECUED_IDENTITY_PASSPHRASE, is the common one. From the same machine, check the health address. It needs no login:

curl --fail http://127.0.0.1:7717/health

A healthy server answers with HTTP 200 and a JSON body that contains "status":"ok". That proves the program is taking requests. It does not prove a connection or a recipe works. Next, read the running server's start-up log. It shows the addresses it can be reached on. It shows the webclient link and the pairing code. For a start-at-login install, run recued logs, or on Linux journalctl -u recued (add --user if you installed without root). Or run recued pair. It prints a fresh code, the server's addresses, and the pairing link.

The code works once. It stops working after 15 minutes. Did it run out before the first pairing? Run recued pair for a new one. Or restart the server with the same database and the same settings, and read the new code from its start-up log. A server is not ready to pair if it cannot write its data directory. The same is true if it cannot open its port, or cannot print a pairing code. Fix that first.

#Reachability is optional

A server that only your own network can reach is a fully working server. Keep it on loopback or a private network unless some other device needs it. Public reach matters only for features that get traffic from outside. Read Reachability before you open firewall ports, DNS, or certificates.

#Next

Attach a client in Pairing and devices.