Skip to content
Edith

Use case

Manage Servers From Your Mac With Edith

Watch, open and fix the machines you reach over SSH without a separate app for each job.

Updated by

Get Edith

The problem

Looking after a few servers from a Mac usually means a terminal for SSH, a separate app for Docker, another for the database, an SSH tunnel you set up by hand every time, and a dashboard in the browser for CPU and disk. Each tool knows nothing about the others, and none of them can be scripted the same way.

This setup uses four Edith extensions that share one list of machines and one command line.

The setup

  1. 1

    Add each machine once

    In Machines, enter an address and username, or pick a host from your SSH config. Your Mac is already listed. Removing a machine later only forgets it; nothing on the machine changes.

  2. 2

    Watch its health

    Machines shows CPU, memory and disk for every host, and the Docker containers running on it. metrics takes one sample, keeps streaming with --follow, and adds the busiest processes with --processes 10.

  3. 3

    Run commands and manage services

    Open a terminal tab on any machine, browse and transfer files, or run one command and get its output and exit code back. Docker containers and Compose groups can be started, stopped, restarted and read from the same place.

  4. 4

    Keep local shells next to remote ones

    Edith's Terminal opens local shells in tabs with ⌘T. Turn on Broadcast to type the same command into every open tab, and use a Machines workspace to arrange terminals from several machines side by side.

  5. 5

    Reach the database through a forward

    Save a port forward on the machine, switch it on, then add a connection in Database that points at the local port. Passwords are stored in your Keychain, and risky changes are previewed and wait for your confirmation.

  6. 6

    Count agents on every machine

    If you run Claude Code or Codex on the server too, Usage runs its collector there over SSH and folds the results into the same dashboard, labelled by machine.

The whole thing as one script

 ed machines add box --host 10.0.0.4 --user deploy
 ed machines metrics box
 ed machines docker ps box
 ed machines docker logs box api
 ed machines exec box -- uptime
 ed machines forwards add box --local 15432 --remote 5432
 ed machines forwards on box 1
 ed database connections add box-db --product postgresql --port 15432 --username app --password-stdin
 ed usage machines enable box
 ed usage machines collect
 ed usage summary --machine box

--password-stdin reads the database password from standard input, tests the connection and stores the password in your Keychain. The connection is saved only if the test succeeds. ed database connections list shows the connection id that ed database connect takes.

Other commands that come up often:

 ed machines services ls box
 ed machines services restart box nginx.service
 ed machines docker compose ls box
 ed machines docker compose restart box web
 ed machines files ls box
 ed machines snippets run box 1

Pitfalls

  • SSH has to work first. Machines signs in with your SSH agent, a private key you name with --key, or a password it keeps in your Keychain. If the host refuses that login from plain ssh, it refuses Edith too.
  • Pick a free local port. A forward fails if something on your Mac already listens on the local port. Use a high port such as 15432 rather than 5432 when Postgres also runs locally.
  • Docker and systemd must exist on the host. The Docker and services views show what the machine reports. A host without Docker has nothing to list.
  • Usage collection skips account-wide feeds. Cloud usage such as Codex Cloud is fetched once on your Mac, not again from each server, so totals are not counted twice.
  • Exec returns the remote exit code. In a script, ed machines exec fails when the remote command fails, which is what you want, but a grep that matches nothing also exits 1.

Go deeper

Agents on your servers also appear on the Agents board, which running multiple Claude Code agents covers, and checking Claude Code usage limits explains what the usage numbers mean.