Set up amux on Linux

This is the first thing to do on a new Linux machine. At the end you will have coding-agent sessions running in tmux, each one surviving a closed laptop lid or a dropped SSH connection, and a single command that tells you whether the machine is set up correctly.

You only need one computer for this. Connecting a second one comes later and changes nothing you do here.

What you need first

• A Linux machine you can log into. Fedora, Ubuntu, Debian, Arch and openSUSE are all fine — the setup script works out which package manager you have.
• A Claude subscription (Pro or Max). Claude Code does not work on the free plan.
• git, and a terminal.

Everything else gets installed along the way.

Step 1 — install Claude Code

curl -fsSL https://claude.ai/install.sh | bash

Then start it once and sign in:

claude

It opens a browser to complete the sign-in. Type /login inside Claude Code if it does not prompt you.

Step 2 — get the commands

git clone https://git.nuilab.org/f.ortega/amux-nui-public.git
cd amux-nui-public
./install.sh

install.sh symlinks the commands into ~/.local/bin, so a later git pull updates all of them at once. If it warns that ~/.local/bin is not on your PATH, follow the line it prints and open a new terminal.

Step 3 — install amux itself

./setup/bootstrap

This works out which platform and package manager the machine has, then installs what is missing — tmux, python3, curl, and amux itself. It asks before each install and prints the exact command it is about to run. Re-running it is safe.

Three flags cover the non-interactive cases: --yes assumes yes to every prompt (for scripted setup), --dry-run prints what it would do without changing anything, and --no-claude skips installing Claude Code.

Step 4 — check the machine is actually ready

amux-doctor

This is the command to run now, and again any time something behaves oddly. It does not guess from version numbers: it starts a throwaway tmux session and runs the exact operations amux depends on, then reports what worked.

A healthy machine looks like this:

Core tools
  ✓ python3 (Python 3.14.6)
  ✓ curl
  ✓ tmux present (tmux 3.7b)
  ✓ tmux supports every call amux makes

amux
  ✓ amux CLI on PATH (/home/you/.local/bin/amux)
  ✓ amux-remote is the amux-nuilab version

Claude Code
  ✓ claude on PATH (2.1.220 (Claude Code))
  ✓ auth: interactive login (/login)
      Chrome integration is available in this mode (claude --chrome).

Anything marked ✗ comes with the command that fixes it. Lines marked ! are worth reading but do not block you.

Step 5 — your first session

Register a project directory, then start it:

amux register myproject --dir ~/code/myproject
amux start myproject

amux start drops you inside the session. Detach with Ctrl-b d — the agent keeps working. Come back with:

amux start myproject

To see everything on this machine at a glance:

amux-ls

example-host (local) · 3 sessions · 2 ● running

 1 ● myproject   2 ● notes       3 ○ scratch

Useful from day one

When something goes wrong

Run amux-doctor first — it identifies most problems by name.

The one worth knowing in advance: if a session says Please run /login and the rest of the line reads 401 The socket connection was closed unexpectedly, that is a network hiccup wearing an authentication error’s clothes. Your sign-in is fine. Wait for the connection to come back and send the message again. Signing in again does not help.

The repository’s docs/troubleshooting.md covers the rest.

Where to go next

Adding a second machine is the next step, and nothing above changes when you do. One machine runs a small server, and amux-config add on the other writes the config file that reaches it — then commands like amux-all and ccjump cover every machine at once. See amux-tools and docs/remote.md in the repository, and Connect machines with hcom for the coordination layer that sits on top.