Maestri Box

Maestri on a server or a dedicated computer. Your agents work there day and night, and you connect from any device.

Read the docs

Give your agents their own computer.

Maestri Box runs Maestri on a VPS or a machine set aside for it. Terminals, agents and the connections between them keep running there around the clock.

Set it up with one prompt.

Paste it into an agent in Maestri, and it walks you through the server, the network and pairing.

Read the prompt
I want to set up Maestri Box: Maestri running with no screen on a Linux server, so my agents keep working when my
computer is off, and I open its canvas from Maestri on my computer and from Maestri Remote on my phone. You are
running inside Maestri on my computer. Guide me from start to finish until my Box shows up in Maestri and works.

HOW TO WORK WITH ME
- One question at a time, in plain words. Explain a term the first time you use it (SSH key, firewall, NAT,
  Tailscale).
- Before each command on the server, say in one line what it does. Ask me before anything that uses sudo.
- Never ask me to paste a password, a license key or a sign-in code into this chat.
- You need Maestro Mode. Run maestri recruit --help first; if it says Maestro only, ask me to turn on Maestro Mode
  for this terminal and wait.
- THE SERVER SHELL. Anything interactive (SSH or sudo passwords, the QR code, a license key) happens in a plain
  terminal you place next to you on the canvas:
    maestri recruit "Server" --command "ssh <user>@<address>"
  Type into it with: maestri ask "Server" --raw "<command>\n"
  Read it with:      maestri check "Server"
  When it asks for a password, tell me to click into the Server terminal and type it there, and wait for me. A
  password prompt does not echo, so you never see it. Use your own shell for quiet checks
  (ssh -o BatchMode=yes ...), and the Server shell for every sudo step, so I see each one run.
- When I need a web page (a provider's console, a sign-in link), open it next to you with:
  maestri portal create "<url>" "<short name>"
- Don't move on until the current step is confirmed working. If something fails, read the error and the logs before
  changing anything.

FACTS
- Install: curl -fsSL https://themaestri.app/box/script.sh | sudo bash
  It installs the maestri-box package, runs it as a systemd service and is safe to run again.
  Options: --user <name> (run it as that existing account) or --system-user (a dedicated "maestri" account, right
  when other people will pair). Variables: MAESTRI_BOX_LISTEN_ADDRESS=<ip> (listen only there, from the first start),
  MAESTRI_BOX_PORT=<port>, MAESTRI_BOX_NO_PAIR=1 (skip pairing at the end).
  Flags go after "bash -s --", variables after "sudo".
- Supported: Ubuntu 22.04 or 24.04, Debian 12, x86_64 or arm64, a KVM VPS, a real machine or an LXC container.
  Not Alpine, not NixOS. 1 GB of memory for the Box alone, 2 GB or more if agents will run on it. About 1 GB of disk.
- It NEVER runs as root. It runs as the account given (or the one that ran sudo), and its agents use that account's
  projects, git, SSH keys and agent logins. A device paired with Full control can do anything that account can.
- Network: TCP 7434. Private with Tailscale (recommended, nothing is opened to the internet), or the port opened in
  the provider's firewall and the OS firewall.
- AWS, Oracle Cloud and Tencent Cloud put the public address in front of the machine (NAT), so pairing needs
  --host <public address>. Hetzner, Contabo, DigitalOcean and similar don't.
- Box commands, all as sudo maestri-box <command>: pair [--host <address>], status (exit 0 means listening), devices,
  remove <device>, password set | clear, license status | activate <key>, config, config port <n>,
  config listen-address <ip | all>, setup --user <name> | --system-user. Logs: journalctl -u maestri-box -n 100.
  After the install, sudo maestri-box --help is the source of truth if it disagrees with this prompt.

STEPS
1. Where. Ask: a VPS I already have, I need a VPS, a spare Linux computer, or Docker.
   - Need a VPS: explain the 1 GB and 2 GB sizes, suggest two or three providers (for example Hetzner, Oracle Cloud's
     free arm64, Contabo), open the one I pick in a portal, and wait while I create it with Ubuntu 24.04 and my SSH
     key. Never fill in sign-up or payment details for me.
   - A spare computer that is a Mac or a Windows PC: stop. Explain that the Box is for Linux, and that I should install
     Maestri on that computer, turn on Wire and leave it running instead.
   - Docker: say it is supported but new, and follow the Containers section of the Maestri Box docs (https://themaestri.app/docs/maestri-box) for the image.
2. Reach it. Ask for the address and the user I log in with. Test:
   ssh -o BatchMode=yes -o ConnectTimeout=10 <user>@<address> true
   - If it fails because there is no key: check ~/.ssh for one and make one with ssh-keygen if needed. Then place the
     Server shell as a plain local shell and type ssh-copy-id <user>@<address> into it (on Windows, which has no
     ssh-copy-id: type $env:USERPROFILE\.ssh\id_ed25519.pub | ssh <user>@<address> "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys").
     I type the server's password there. Test again, then type ssh <user>@<address> into the same shell.
   - Otherwise place the Server shell with ssh as above.
   - If I log in as root: ask for a name, create that account (adduser --disabled-password, then copy root's
     authorized_keys to it). The Box will run as that account; you keep using root to install.
3. Check the machine. In your own shell:
   ssh <user>@<address> 'curl -fsSL https://themaestri.app/box/script.sh | bash -s -- --check'
   It changes nothing and prints one ok, warn or fail line per check, each with its fix. Tell me in one or two
   sentences whether it fits. Stop on any fail and walk me through its fix.
4. Network. Ask: Tailscale (recommended) or an open port?
   - Tailscale: check whether this computer has it (tailscale status). If not, open https://tailscale.com/download in
     a portal for me. On the server: curl -fsSL https://tailscale.com/install.sh | sh, then tailscale up, which
     prints a sign-in link: open it in a portal and tell me to use the same account as on this computer. Read the
     server's address with tailscale ip -4.
   - Open port: open the provider's firewall page in a portal and tell me exactly which inbound rule to add: TCP 7434,
     from my own IP if I know it. On the server, if ufw is active: ufw allow 7434/tcp. Oracle Cloud also needs
     iptables -I INPUT -p tcp --dport 7434 -j ACCEPT and netfilter-persistent save. Tell me once that anyone who
     reaches the port can try to pair, and that they still need a code.
5. Install. Tell me what the command does, then type it into the Server shell. Logged in as root, with the account
   from step 2:
   curl -fsSL https://themaestri.app/box/script.sh | MAESTRI_BOX_NO_PAIR=1 [MAESTRI_BOX_LISTEN_ADDRESS=<tailscale ip>] bash -s -- --user <name>
   As a normal account:
   curl -fsSL https://themaestri.app/box/script.sh | sudo MAESTRI_BOX_NO_PAIR=1 [MAESTRI_BOX_LISTEN_ADDRESS=<tailscale ip>] bash
   If sudo asks for my password, I type it there. Then check: sudo maestri-box status must exit 0.
6. Pair this computer. Type into the Server shell:
   sudo maestri-box pair [--host <public address, only behind NAT>]
   It shows an address, a six-digit code and a QR code, renews the code every five minutes and waits. Tell me: in
   Maestri, open Settings > Wire, turn Wire on if it is off, then Devices > Connect to Another Computer, and enter the
   address and the code from the Server terminal. When pair reports a device, check with sudo maestri-box devices.
   If my computer can't connect: type sudo maestri-box doctor into the Server shell and follow the fix on each warn
   or fail. From this computer, nc -vz <address> 7434 with no answer means the firewall or the wrong address: go back
   to step 4.
7. Prove it. Ask me to open Spaces in Maestri, open the Box, open its workspace and start a terminal there. Wait for
   me to say it works.
8. Offer, one at a time, each optional:
   - My phone: type sudo maestri-box pair into the Server shell again and ask me to scan the QR code there with
     Maestri Remote.
   - Agents on the Box: in a terminal on the Box's canvas, install Claude Code or Codex there and sign in. The sign-in
     link opens on my side; I type any code myself.
   - License: the Box starts a 7-day trial. To activate, type sudo maestri-box license activate into the Server
     shell. It asks for the key without showing it; I paste it there.
   When we're done, ask before you dismiss the Server shell (maestri dismiss "Server").
9. Wrap up with a note on the canvas: maestri note create with the Box's address, the account it runs as, the network
   choice, how to add a device (sudo maestri-box pair), how to update (sudo apt upgrade), and where the logs are.
   Nothing secret in it.

RULES
- Never run the Box as root. Never turn off a firewall wholesale. Never open port 7434 without telling me what that
  means.
- No passwords, keys or codes in files, notes, logs or this chat.

Rather do it yourself? Follow the guide in the docs

Same license. Same price.

A new Box starts with a 7-day trial. After that it keeps one workspace free, or a Pro license unlocks all of them.

Free

$0forever

  • 1 workspace
  • Unlimited agents
  • All features included

Pro

$18one-time payment

  • Everything in Free, plus:
  • Unlimited workspaces
  • The same license as Maestri on Mac, Windows and Linux
  • 7 days free, then pay once

Already have a license? Activate the Box with one of its seats.

Requirements

Linux
Ubuntu 22.04 or 24.04, or Debian 12.
Processor
x86_64 or arm64.
Memory
1 GB, or 2 GB if agents run on it. About 1 GB of disk.
Network
A port open to your devices, or a private network.