Your first MoxiVue setup, from download to your first machines

Install MoxiVue Console on the computer you work at

You manage everything from MoxiVue Console, the window. Install it first, on your own computer.

MoxiVue Console needs Ubuntu 22.04 or newer with a desktop (tested on 22.04, 24.04 and 26.04), on amd64 or arm64. MoxiVue runs on Linux; macOS returns in a later version. Add our package source once and install it; later versions then come with your other updates:

curl -fsSL https://get.moxivue.com/apt/moxivue-archive-keyring.gpg | sudo tee /usr/share/keyrings/moxivue-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/moxivue-archive-keyring.gpg] https://get.moxivue.com/apt stable main" | sudo tee /etc/apt/sources.list.d/moxivue.list
sudo apt update
sudo apt install moxivue-console

Check the signing key. Before you trust the package source, show the key you added:

gpg --show-keys /usr/share/keyrings/moxivue-archive-keyring.gpg

It must be called "MoxiVue packages" and have the fingerprint 4704 4752 DC5B F50C 34D5 0367 139F A85F D421 7C65. apt then refuses any package that this key did not sign. This page and the key come from our servers, so a match shows the key arrived intact, not that our servers are honest. For a check that does not depend on them, see check a release yourself.

Open MoxiVue from your applications. moxivue status shows this computer at a glance, with your console apart from the machine.

Consoles and agents: two kinds of device

A console is where a person works: it holds that person's keys for the account. A machine is what you look after. The package you install decides which a computer is.

• One or the other. A computer has one of the two packages. Installing one replaces the other.
• A person's keys and a machine's keys never mix. Your console's keys belong to you and to one account, in files only your user account can open. A machine has keys of its own, held by the system user moxivue.
• Owner and admin computers host no sessions. A computer that holds an owner or admin console of an account opens no terminal, forward or root action there for anyone else: a shell on it could reach those keys. Reach machines that run MoxiVue Agent instead.
• Scripts never use your console. For machines added by a script, use install tokens (below): they join machines, nothing else.

What each role may do is on Accounts and roles.

Sign in, create your account and become its owner

The console that creates the account is its first owner. Creating one needs a sign-in. You sign in, give the account a name, and write down the recovery paper it shows once.

1. Sign in. Settings → Account: enter your email address and click Email me a code. Type the 6-digit code from that email and click Sign in. On the command line:

   moxivue login --email you@example.com

   Signing in tells our server who you are. It gives nobody a key to your machines, and it gives no role in an account.
2. Create the account. The Account tab → Create an account: enter its name (your company, for example) and click Create the account. On the command line:

   moxivue account create --name "Your company"

   Creating an account needs that sign-in, and for now an invite code too. Ask at hello@moxivue.com.
3. Write down the recovery paper. It is shown once, starts with mxr1-, and belongs on paper or in a safe place offline. It holds no key to your data. It can only ask for a recovery, which every owner and admin console of the account is shown and can cancel, and which completes only after 7 days (below).
4. Write down the account fingerprint. The Account tab shows it, and moxivue fingerprint prints it: 64 hex digits made from the account's first log entry. Every console and machine of the account shows the same one. Keep it with the recovery paper; install tokens ask for it (below).

Your console is now the owner of the whole account. Two safeguards are on from the start and cannot be switched off:

• A second console confirms. Every console that joins, and every sensitive change, waits until another owner or admin console confirms it: one that did not propose it and is not its subject. The one exception is the second console itself, which joins while yours is still the only device.
• The console lock. Inviting, confirming, adding machines, opening terminals and cancelling a recovery need this computer's own password first. The console then stays unlocked for 15 minutes, counting time asleep, and locks with the screen: Unlock in the Account tab, or moxivue unlock.

How a console joins, and what you compare

A console joins with an 8-digit code from a console that is already in. Then three words prove that the two screens are talking to each other, and not to someone in between.

1. Make a code on a console that is in. The Account tab → Invite a console…: choose the role (and, for a technician, the site or group), then Make a code. On the command line:

   moxivue invite --role admin

   The code has 8 digits, works for one try and lasts 15 minutes. Give it to the person by a way you trust, such as reading it out.
2. Join on the new console. Sign in there first, then the Account tab → Join an account, enter the code and click Join, or moxivue join <code>. The new console shows three words.
3. Type the three words on the inviting console. They are made from the exchange itself on both sides: if anyone tampered with it, the words do not match and nothing joins (the command ends with status 4). Click Propose this console, or:

   moxivue invite words <run> "word1 word2 word3"

4. Confirm on another console. A second owner or admin console is shown the change, who proposed it and the three words, worked out again on its own. Compare them with the new console's screen in person, or by voice with someone you know, then click The words are the same: confirm, or moxivue confirm and moxivue confirm <id>.

Our server, the MoxiVue Dispatcher, carries the exchange but never sees the code or the words, so it cannot guess them, and a wrong guess uses the code up. After three failed tries in an hour, the inviting console waits longer before it makes another code. Every join is an entry in the account's signed log that every console and machine checks for itself.

Three consoles before the first machine

An account takes machines only once it has three owner or admin consoles for the whole account, two of them owners, on separate computers. Then losing one, or one being stolen, never leaves you without a way to act.

Until then the account is being set up: the Account tab and moxivue overview say "it has n of the 3 owner or admin consoles it needs", only owner and admin consoles can join, and no machine and no install token is accepted.

1. Install MoxiVue Console on a second computer, such as your spare laptop, and sign in there.
2. On your console, invite it with the role owner (moxivue invite --role owner) and join it as above. As the first console to join, it needs no confirmation.
3. Install a third console, for a partner or a senior technician, and invite it as owner or admin. This time the console you did not use to invite confirms it, after comparing the words.

With three such consoles, two of them owners, the set-up is done and the account is ready for machines. From then on it never has fewer: removing one of the three waits until another has joined, so any one of them can always be removed by the other two. One person may hold all three on three computers; another console of the same person then confirms.

Technicians, and how far their role reaches

A technician's console joins like any other, with the role and reach you choose in the invitation.

• The role. Operator for someone who opens terminals, admin for someone who also adds machines, invites and changes settings, viewer for someone who only looks, auditor for someone who reads the audit log and plays recorded sessions and nothing else. You can give a role up to your own; owners and auditors are invited only by an owner.
• The reach. A role reaches the whole account, one site, or one group inside a site: moxivue invite --role operator --site Dallas --group "Front desk". A console placed in a site cannot see, open or change anything outside it, and never holds the keys of another site's data.
• Joining waits for a confirmation. Like every console, a technician's console joins only after another owner or admin console has compared its three words.

The full table of what each role may do is on Accounts and roles.

Sites, groups and people

Sites and groups decide how far a role reaches. People let you remove everything of one person at once.

• Sites and groups. A site is a place such as an office; a group is part of a site, such as a floor or the front desk. An owner or admin of the whole account adds them in the Account tab, or with moxivue site add Dallas and moxivue group add Dallas "Front desk". Each new site or group, and each rename, waits for another console's confirmation.
• Moving a console or machine. Choose its site or group in the Account tab, or moxivue place <device> --site Dallas. A move, like any change of role or reach, is a sensitive change: another console confirms it.
• People. Name the people who use the account and give each console to one of them: moxivue person add "Dana Smith", moxivue person set <console> <person>. When someone leaves, moxivue person remove <person> removes all their consoles in one step, once another console confirms it.
• Roles later. moxivue role <console> admin changes a role, never above your own; only owners make owners. moxivue remove <device> removes a console or a machine. Both wait for another console's confirmation.

Names of the account, sites, groups and people are sealed in the account's log: your consoles read them, the Dispatcher and the witnesses do not. They see only numbers for places and people, with roles and reach.

Customers

Each customer is an account of its own, with its own keys, recovery paper, owners and signed log.

Create a customer's account from your console the same way as your own (Create an account, or moxivue account create --name "Acme Dental"), then give it its own three owner and admin consoles before its first machine. Your console holds separate keys for each account it is in; the Account tab lists them, and --account <account> chooses one on the command line. One customer's data cannot be opened with another customer's keys.

Add machines: servers, Raspberry Pis and workstations

The machines you look after run MoxiVue Agent. Each joins once root on the machine says yes, and once the number on the machine and the words on your console match.

1. Install MoxiVue Agent on the machine. Add the package source and check its key as in the first step, then install the agent and start it:

   sudo apt install moxivue-agent
   sudo moxivue service enable

   The machine agent runs as the system user moxivue, never as root, starts at boot with nobody signed in and starts again by itself if it stops.
2. Start the join on your console. The Account tab → Add a machine…, with its site or group. On the command line:

   moxivue machine add --site Dallas

   It shows a short rendezvous text for the machine.
3. Join on the machine, as root.

   sudo moxivue machine join <rendezvous>

   Root on the machine agrees to its joining, which is recorded in a file only root can change. The machine shows which account it is joining and what owners and admins may do there once the account allows it, then an 8-digit number.
4. Type the number on your console and click Accept this machine, or moxivue machine accept <rendezvous> --number <number>. Your console then shows three words.
5. Type the three words on the machine. Only then does it join. A wrong number or wrong words end the join with nothing done.

The machine now appears on the account's consoles in its site or group. One owner or admin is enough to add a machine; every owner and admin console is told. Joining is accepting management: from then on, what may happen on the machine is decided by the account's owners and admins, within the roles on Accounts and roles, and every connection shows a notice on the machine's desktop where it has one. Terminals and forwards to a new machine stay off until an owner or admin switches them on, and switching them on waits for another console's confirmation (the guide has the steps).

Up to 10 machines per account. An account holds at most 10 machines; consoles do not count. An 11th is refused with "This account has 10 machines, the most this version allows. Write to support@moxivue.com for more." Removing a machine frees its place.

Many machines at once: install tokens

For machines set up by a script, an owner or admin makes install tokens: each joins one machine, once, within the hours you choose.

moxivue token issue --count 5 --hours 4 --site Dallas

Each token lasts 1 to 24 hours, joins one machine only, can never join a console, and is shown once. The command prints the line to run on each machine, with the account's full fingerprint (64 hex digits): the machine joins only the account with that fingerprint and ends with status 4 otherwise, so a token given to the wrong script cannot lead a machine elsewhere. Tokens are refused while the account is being set up. moxivue token list shows them as open, used, revoked or expired, and moxivue token revoke <id> ends one that is no longer needed.

The recovery paper

If you lose every console, the recovery paper gets you back in: slowly, and in view of everyone else in the account.

1. Install MoxiVue Console on a new computer, sign in, and choose Recover an account with its paper… in the Account tab (or moxivue recovery start --account <account>). Type the paper there.
2. Every owner and admin console of the account shows the request with a Cancel button. The two witnesses, servers that keep an account's state honest (how), hold it too, so the Dispatcher cannot hide a cancel.
3. After 7 days, counted by the witnesses, the new console completes it (moxivue recovery complete): it becomes an owner, the consoles named in the request are removed, the account's data gets new keys, and a new recovery paper is shown on a separate new console. If one of the named consoles cancels, the wait grows by 14 days; a cancel from another owner or admin console ends the request.

To replace a paper that may have been seen: Replace the recovery paper… in the Account tab, or moxivue recovery replace. The new paper is shown on a separate new console, and another console confirms the change.

Checklist: every verification, in order

1. The package key you added shows "MoxiVue packages" and the fingerprint above.
2. Your email address is confirmed with the 6-digit code sent to it.
3. The recovery paper is written down and kept offline, with the account fingerprint next to it.
4. For every console that joined, its three words matched on the inviting console, and another console compared them with the new console's screen before confirming.
5. The account has three owner or admin consoles, two of them owners, on separate computers, and is no longer being set up.
6. Each technician's console has the role and the site or group you meant, and is given to its person.
7. Every console and machine shows the same account fingerprint.
8. Each customer has its own account, recovery paper and three consoles.
9. For every machine, root agreed on the machine, the number matched on your console and the words matched on the machine.
10. Install tokens you no longer need are revoked, and the audit log lists every join you expect.

Next: the user guide covers alerts, terminals, SSH, recordings and updates.