Guides
Set up a Linux server
The usual case is a VPS or a box under the desk running Ubuntu or Debian. Here's the setup, start to finish.
On this page
This guide sets up a fresh Ubuntu or Debian server for Mucq: a user for your work, tmux, Claude Code, Mucq's key and a projects folder. The commands are for Ubuntu and Debian; other distributions differ mostly in the package manager.
You need a shell on the server to start with: an SSH session from Terminal, or your provider's web console.
1. A user for your work
Run Claude as an ordinary user, not as root. If the server only has root so far, create one (here, you) and let it use sudo:
sudo adduser you
sudo usermod -aG sudo you
As root, leave out sudo; a minimal Debian may need apt install sudo first. Then continue as the new user:
su - you
2. tmux
sudo apt update && sudo apt install -y tmux
That's all the tmux setup there is. Mucq doesn't need a ~/.tmux.conf; see tmux for what it sets itself.
3. Claude Code
Install Claude Code for this user the way Anthropic's setup guide describes. Then start it once, sign in, and leave it with /exit:
claude
Mucq starts Claude in tmux's shell, which is a login shell, so if claude works after a fresh login, it works in Mucq.
4. Mucq's key
In Mucq, add the server: Host devbox.example.com, User you, Sign in with SSH Key. Choose Copy Install Command, paste it into the shell on the server and press Return. It appends the key to ~/.ssh/authorized_keys and sets the permissions sshd insists on.
Do the same once from your iPhone and your iPad, if you use them: each device has its own key.
5. The projects folder
Make a folder for your projects, with each project in a folder of its own:
mkdir -p ~/projects/webshop
Or clone a repository into ~/projects. In Mucq, set Projects folder to ~/projects. Every folder inside it becomes a project you can pin.
6. Connect
After Add Server, Mucq lists the projects folder and asks you to confirm the server's host key. Compare the fingerprint it shows with the server's own:
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
Choose Connect, pin webshop and open it. Claude starts in ~/projects/webshop.
7. Keys only
Once Mucq connects with its key, turn password logins off. Keep your current SSH session open until you've checked that a new key login still works.
printf 'PasswordAuthentication no\nKbdInteractiveAuthentication no\n' | sudo tee /etc/ssh/sshd_config.d/010-key-logins.conf
sudo sshd -t
sudo systemctl reload ssh
sudo sshd -t prints nothing when the configuration is valid. A file of your own in sshd_config.d stays put when a package update replaces /etc/ssh/sshd_config.
Careful
If Mucq signs in to this server with a password rather than a key, skip this step: it would lock that login out.
If the server is older
Mucq needs an Ed25519 or ECDSA host key and AES-GCM encryption; current Ubuntu and Debian have both. If Mucq says it has no SSH algorithms in common with the server, its message names the fix. A missing host key type is one command away:
sudo ssh-keygen -A
sudo systemctl reload ssh
ssh-keygen -A creates every host key type the server lacks and leaves existing ones alone. Next: reaching your server from wherever you are.