Set up Moxon Metrics and get the most from it

Install with apt (recommended on Linux)

Add the package source once, then install; later versions come with sudo apt upgrade like any other software.

curl -fsSL https://get.142-93-115-168.sslip.io/apt/moxon-archive-keyring.gpg | sudo tee /usr/share/keyrings/moxon-archive-keyring.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/moxon-archive-keyring.gpg] https://get.142-93-115-168.sslip.io/apt stable main" | sudo tee /etc/apt/sources.list.d/moxon.list
sudo apt update
sudo apt install moxon-metrics

• Servers: sudo apt install moxon-metrics-headless, then sudo moxon service enable --user <name> and moxon join <code>.
• Going back to an earlier 4.x: sudo apt install --allow-downgrades moxon-metrics=<version>; apt-cache policy moxon-metrics lists the versions on offer.
• Preview channel: for testing upcoming versions. Use preview instead of stable in the second line, or add a second line with preview to get whichever is newer. To leave it, change it back to stable and run sudo apt update.
• Checking the key: gpg --show-keys /usr/share/keyrings/moxon-archive-keyring.gpg shows "Moxon Metrics packages" and its fingerprint; the fingerprint is also on the security page.
• Removing the source: sudo rm /etc/apt/sources.list.d/moxon.list /usr/share/keyrings/moxon-archive-keyring.gpg.

Install on Linux

Version 4.0 needs Ubuntu 22.04 or newer (tested on 22.04, 24.04 and 26.04) and comes for amd64 (Intel and AMD) and arm64 (Raspberry Pi and other ARM machines; run dpkg --print-architecture if unsure). There are two packages; install one or the other on a machine, and installing one replaces the other. With apt (above) you get the same packages and later updates.

Desktop

1. Download moxon-metrics_4.0.1_amd64.deb or the arm64 file.
2. In your Downloads folder run:

   sudo apt install ./moxon-metrics_4.0.1_amd64.deb

   Type ./ before the file name, or apt looks for a package of that name online.
3. Open Moxon Metrics from your applications. The agent starts straight away and keeps running after you close the window, and after restarts; the tray icon shows live readings.

The helper runs as root because per-app network use, everyone's disk use, drive health and listening to the network need it. It only reads: it accepts no input and changes nothing.

Server (headless)

For machines with no desktop. It installs the agent, the helper and the moxon command line, without any window or desktop libraries.

1. Download moxon-metrics-headless_4.0.1_amd64.deb or the arm64 file, and copy it to the server.
2. Install it:

   sudo apt install ./moxon-metrics-headless_4.0.1_amd64.deb

3. Start the agent as a system service for the account it should run as. It starts at boot, with nobody signed in. It refuses to run as root.

   sudo moxon service enable --user <name>

4. Join your relay account, as that user. Get a code from Settings → Relay → Add a device on a connected machine, or with moxon pair on one:

   moxon join <code>

5. Check that every part works:

   moxon verify

The server now appears under Machines → Through your relay on your other devices. To allow terminal sessions to it, run moxon terminal on --allow <device> (add --no-ask if nobody is there to answer the prompt). moxon help lists every command.

Upgrading from 3.3

Install the 4.0 package over 3.3 in the same way, or run sudo apt upgrade if you use apt. History, settings and relay pairing are kept, and the 3.3 background services are replaced by the single 4.0 agent. Upgrading is tested on Ubuntu 22.04, 24.04 and 26.04, on amd64 and arm64.

Mac and Windows

The Mac and Windows versions are being rebuilt on the 4.0 core and are not available for download at the moment. If you already have the Mac version installed, it keeps working; uninstall it with sudo "/Applications/Moxon Metrics.app/Contents/Resources/uninstall.sh".

First look

The top of the window shows the machine, its system and three status lights: Recording, Network per app (the helper) and Alerts. All three should be green within a minute of installing. Below them are the tabs:

• Live: the machine right now. Click an app in "Apps right now" to see its processes; use Pause to freeze the list while you read it.
• Processes: every process as a list or tree; click one for details and actions.
• Network: internet latency, Wi-Fi, interfaces, connections per app and monthly data use.
• Topology: the map of each network the machine is on.
• System: drives and their health, memory, pressure, sensors, containers, services and startup apps.
• History: up to 30 days; click any bar to see which apps were busy then.
• Machines and Settings.

In 4.0 the tabs run down the left side, with a Wireless tab on machines with Wi-Fi or a mobile modem and a Capture tab for packet capture. The Basic / More / All switch sets how much each tab shows: start with Basic and switch up when you want the detail.

The feature tour describes each tab in detail.

Recording and history

Settings → Recording:

• Reading every: 1 to 60 seconds (5 by default). Shorter catches brief spikes; longer saves a little power. The recorder restarts by itself when you change it.
• Keep history for: how many days to keep. The estimate next to it shows how much disk space that takes.
• Accurate app memory: splits memory shared between apps fairly, measured once a minute, so apps aren't counted twice.
• Live charts show: how much of the past the Live charts keep on screen.

To keep a record outside the app, open History, choose a range and use Export: readings or per-app use as CSV, saved in your Documents folder.

Alerts and where they go

Settings → Alerts: switch on the master switch, then tick each alert you want and set its limit. Repeat each alert at most every keeps a lasting problem from flooding you.

Under Where alerts go, every switched-on channel receives every alert. Save settings before using Send test.

Desktop

Notifications on the machine itself. On by default.

ntfy (free push to your phone)

1. Install the ntfy app on your phone and subscribe to a topic with a long, hard-to-guess name, for example moxon-7Fq2kx9.
2. In Settings, enter the topic link: https://ntfy.sh/moxon-7Fq2kx9, switch ntfy on, save and send a test.

Urgent alerts (battery, temperature, pressure, drive health) are sent with urgent priority, so they can break through Do Not Disturb if you allow it in the ntfy app.

Telegram

1. In Telegram, talk to @BotFather, send /newbot and follow the steps. Copy the token it gives you.
2. Send any message to your new bot, then open https://api.telegram.org/bot<token>/getUpdates in a browser and copy the chat → id number.
3. Enter the token and chat ID in Settings, switch Telegram on, save and send a test.

Email

Enter your mail server, port, security (STARTTLS on port 587 or SSL/TLS on 465), user name, password, sender and recipient. With Gmail or Outlook, use an app password rather than your normal password.

Tokens and passwords are stored only in your settings file, readable by you alone, and are never shown back in the window.

SMS and WhatsApp (4.0)

Both use your own provider account, and your provider charges per message. In Settings → Alerts → Where alerts go:

• SMS: choose Twilio (account SID, auth token and the number to send from) or Other provider (the provider's web address, an optional header such as an API key, and the message body with {to} and {text} where the number and message go). Enter the numbers to send to.
• WhatsApp: choose a Meta business account (phone number ID, access token and an approved message template with two text fields: the alert and its details) or Twilio.
• Set At most … a day and quiet hours (for example 22-7). During quiet hours only urgent alerts are sent. If a message can't be sent and email is set up, the alert goes by email instead.

Save, then use Send test.

Data caps

For metered connections such as mobile hotspots: Settings → Network → Monthly data caps, enter gigabytes per month for each network. The Network tab shows use against the cap, and the data-cap alert warns at 80% and 100%.

Managing processes, services and startup

• End a process: in Processes, click it, then End. If it doesn't close, use Force end. Only your own processes can be ended; system and desktop processes are protected.
• Pause a process that is hogging the machine, and Resume it later.
• Priority: lower a background job's priority so the rest stays responsive. Raising priority asks for your password.
• Services (System tab): start, stop, restart, enable or disable. System services ask for your password; core services can't be changed.
• Startup apps (System tab): switch off what you don't need at login to speed up starting.

Mapping a network

The Topology tab fills in by itself as the machine talks to devices and hears them announce themselves. To find everything that is switched on, press Scan network and confirm. The scan takes a minute or two, checks common services, and is gentle on the network.

• Click a device for its maker, names, services and when it was first and last seen.
• If you are plugged into a managed switch, Heard on this interface usually shows the switch name, your port and VLAN, from LLDP or CDP.
• Path to the internet traces the route hop by hop when you press Trace.
• Switch on the New devices alert to hear about anything new on a network the machine has known for at least a day.

Only scan networks you own or look after.

Machines on the same network

1. On the machine you want to view: Settings → Sharing → Switch on, then copy the link (or show the QR code).
2. On the machine you are using: Machines, paste the link, optionally name it, and click Add machine.
3. Its card shows a live summary; Open dashboard shows its full window inside yours, with a bar to come back.

A browser opening the link directly warns once about the certificate, because it was made on the machine. Check the fingerprint under Sharing matches. The app itself pins the certificate when you add a machine. New key stops every old link.

Prometheus and Grafana

With sharing on, each machine serves its readings at https://<address>:8765/metrics, protected by the same access key. A Prometheus job looks like this:

scrape_configs:
  - job_name: moxon
    scheme: https
    tls_config: { insecure_skip_verify: true }
    authorization: { credentials: "<access key>" }
    static_configs:
      - targets: ["192.168.1.50:8765"]

Your machines from anywhere

The relay connects your machines across different networks. Each machine connects out to it, so you open nothing on your router, and everything is encrypted with a key only your devices hold (how).

First machine

1. Settings → Relay → First machine? Create your account. Enter your invite code and click Create account.
2. Write down the recovery code it shows and keep it somewhere safe, such as a password manager. It is the only way back in if you lose every device, and anyone who has it can read your machines.

More machines

1. On a connected machine: Settings → Relay → Add a device. It shows a code that works once, for 10 minutes.
2. On the new machine: Settings → Relay → Already have an account? Join it, enter the code and click Join with code.

Your machines appear under Machines → Through your relay, with their dashboards one click away. Remove a lost or retired device from the list on any other device; it loses access at once.

Invite codes are handed out while the relay is in testing.

Your phone

1. On a connected machine: Settings → Relay → Add a device.
2. Scan the QR code with your phone's camera, or open the relay address on the phone and type the code.
3. Your machines appear with their live summary and history, over Wi-Fi or mobile data. Add the page to your home screen to keep it one tap away.

Terminal

On the machine you want to reach

1. Settings → Terminal: switch on Allow terminal sessions.
2. Tick the machines that may connect. Leave Ask me each time on unless nobody sits at this machine.
3. Save.

From another machine

1. Machines → Through your relay → open the machine's dashboard, then the Terminal tab, and click Open terminal.
2. If the machine asks each time, someone there clicks Allow within a minute.
3. Work as usual: full-screen programs and resizing work. Click End session or close the window when done.

The Terminal tab in a machine's own window opens a shell on that machine. Sessions end after 15 minutes without typing or after 8 hours. On the machine, a banner shows any open session with an End button, and Settings → Terminal lists recent sessions and refusals.

Servers and machines nobody signs in to

With 4.0, use the server (headless) package: see Install on Linux. It runs the agent as a system service for the user you name, with no desktop and nobody signed in.

With 3.3 on Linux, recording runs as your user. To keep it running without a desktop session, run this once:

sudo loginctl enable-linger $USER

A Mac records while its user is signed in.

Capturing packets (4.0)

1. Open the Capture tab and choose the interface. Optionally enter a capture filter (tcpdump syntax, for example port 53) and a time limit.
2. Start, and enter the administrator password. Packets appear as they arrive; click one for its decoded detail and hex.
3. Stop, then Save .pcap to write a .pcap file to Documents/moxon-metrics/captures for Wireshark.

Only headers are kept unless you choose full packets. Only capture on networks you own or look after.

Update and uninstall

Update: if you installed with apt, sudo apt update && sudo apt upgrade. Otherwise download the new package and install it the same way. Settings, history and relay connections are kept.

Uninstall on Linux:

sudo apt remove moxon-metrics

The server package:

sudo moxon service disable --user <name>
sudo apt remove moxon-metrics-headless

On a Mac:

sudo "/Applications/Moxon Metrics.app/Contents/Resources/uninstall.sh"

Both keep your data. To remove it too, delete ~/.local/share/moxon-metrics and ~/.config/moxon-metrics on Linux, or ~/Library/Application Support/Moxon Metrics on a Mac. If the machine was on your relay, remove it from Machines → Through your relay on another device first.

Troubleshooting

"Recorder stopped" at the top of the window

Click Start recorder. On Linux 3.3, systemctl --user status moxon-metrics-collector shows why it stopped; on 4.0, systemctl --user status moxon-agent.

Something isn't working on 4.0

Run moxon verify: it checks every part and says which one fails. moxon logs shows the agent and helper logs (-f to follow). On a server, sudo moxon service status --user <name> shows the service.

"Network per app off"

The helper isn't running. On Linux, check systemctl status moxon-metrics-helper; on a Mac, reinstall the package.

A relay machine shows as offline

It is asleep, switched off or has no internet. Machines reconnect by themselves when they wake. On the machine itself, Settings → Relay → Reconnect reconnects at once.

"Access key needed" when opening a sharing link

Open the whole link (it ends in ?k=…) or scan the QR code again. After New key, old links stop working.

An iPhone or iPad refuses a sharing link with no option to continue

Update the shared machine to the latest version; it makes a certificate Apple devices accept.

Wi-Fi network name shows as hidden on a Mac

Allow Location access for Moxon Metrics in System Settings → Privacy & Security → Location Services.

A terminal request says terminal access is off on that machine

Switch it on at that machine (Settings → Terminal) and tick the machine you are connecting from.

Questions

Does it slow my machine down?

The recorder reads what the system already counts; with the default 5-second reading it is a small fraction of one processor core. A longer interval makes it lighter still.

How much disk space does history take?

Settings → Recording shows an estimate for your interval and history length. Per-app use is summarised in 30-minute blocks to keep it small.

Can the relay operator see my data?

No. The relay carries and stores only encrypted data, and the key never leaves your devices. See Security and privacy.

Can I run my own relay?

Not yet. A self-hosted relay is on the list of what comes next.

Is there a Windows version?

Windows and Mac development is paused. Both will be rebuilt on the 4.0 core.

I use 3.3. Should I upgrade?

4.0 is the current release and 3.3 gets no new features. Upgrading keeps your history, settings and relay pairing; see Upgrading from 3.3.