>_ clavarium

How you install it

On Ubuntu, one command. It asks nothing, and can be run again to upgrade.

Install on Ubuntu

Ubuntu Server 24.04 or 26.04. In its terminal:

git clone https://example.com/clavarium.git
cd clavarium
sudo deploy/install.sh \
  --domain clav.example.com \
  --operator you@example.com
  • Your sub-domain and your email instead of the examples.
  • No domain yet? --local instead of both: try it first.
  • Windows and Mac: later.

Choose an AI provider

A subscription you have (Claude, ChatGPT), or a key from a service that hosts models, in Europe if you like. What an agent reads goes to that provider.

How to start, if you do not code

  1. A small computer, left on. A mini PC does. Put Ubuntu Server on it.
  2. Point a name of yours to it. No public address at home?
  3. Paste the lines above in its terminal. Keep the password it shows.
  4. Open your address in a browser, on your phone too. Sign in.
  5. New conversation: pick an agent, and sign in to your AI provider in its window.
  6. Give it a folder. Say what you want, in plain words.

Steps 1 to 3 are the only technical ones: ask someone who knows Linux, once.

What it needs

  • A small machineUbuntu Server 24.04 or 26.04, on a processor that can run virtual machines. A mini PC does.
  • 1 to 2 GB of memory per agent at workand a few GB of disk each. An agent asleep costs no memory. Tried on 4 cores, 6 GB, 40 GB.
  • A name for itA domain or a sub-domain of yours, pointing to the machine, or to its relay.
  • An AI of yoursA subscription, or a key from a service that hosts models. clavarium brings none and charges nothing.

What the command sets up

  • An account that owns its data and nothing else, and the one program it may run with more rights.
  • The address in https, a sign-in in front of everything, and a password for each operator, shown once.
  • The key that opens the sealed secrets, kept apart from the data.
  • Each piece it downloads is a named release, checked against a checksum written in the script.

To try it first, with no domain

No name, no sign-in: the page answers on that machine only.

sudo deploy/install.sh --local

# from another computer of yours
ssh -L 7717:127.0.0.1:7717 you@that-machine     # then http://127.0.0.1:7717
  • Whoever can open a page on that machine is its operator: not for a machine other people use.
  • For real use, run the installer again with a domain and an operator.

No public address at home?

The machine at home dials out to a small machine that has one. Home opens no port.

# at home
sudo deploy/install.sh --domain clav.example.com \
  --operator you@example.com --relay relay.example.net

# on the relay, with the line the first command printed
sudo deploy/relay.sh --key "ssh-ed25519 AAAA…"
  • The relay carries bytes. Encryption starts in your browser and ends at home.
  • It holds no certificate and no secret of yours.
  • One record in your domain keeps whoever runs the relay from obtaining a certificate for your name; the script says which.

Then, your agents

  • Claude Code: you sign in once in its terminal, with your own subscription.
  • OpenCode: with the key of a service that hosts models; tried with open models hosted in Europe.
  • Another agent that runs in a terminal: one entry in config/tools.json (its name, its command, how to install it).

Two things that need a key of yours

  • Dictation: a service that turns speech into text.
  • Answers while you are away: a service that hosts several models.
  • Both are optional, set on the machine, and can be the same key.

Keeping it

sudo deploy/backup.sh --to /path/to/a/folder
sudo deploy/restore.sh ARCHIVE.tgz --check     # reads, changes nothing
sudo deploy/restore.sh ARCHIVE.tgz --vault-key FILE
  • Two files, to keep in two places: the archive, and the key that opens its secrets.
  • A restore that does not come back up puts back what was there.
  • Not in a backup: the machines of the agents. What must outlive one belongs in an attached folder.

What was really tried

  • The installer, on a fresh Ubuntu 24.04 and a fresh 26.04.
  • The relay, on a real one, with a machine at home behind it.
  • A backup, a restore, and a restore that fails and puts things back.
  • The mode to try it with no domain, on a fresh Ubuntu 24.04: under eight minutes, no sign-in, nothing listening to the outside.

What was not, yet

  • A certificate obtained by the installer on a machine with its own public address.
  • A mailbox at one of the large mail providers.
  • A conversation started inside that trial: ours ran three machines deep, and the innermost one did not start. On a real computer there are two.