Tutorial 7: Running malac on a server

The agents do not have to run on your laptop. In this tutorial you install malac on a Linux server, pair your Mac with the server’s daemon through an SSH tunnel, start work in the full-screen UI, close the laptop, and check on the agents later from the Mac or a phone.

You need a Linux server you can reach with ssh devbox (any name works; replace devbox throughout), a Mac with malac from tutorial 1, and a provider key for the server. Nothing on the server is exposed to the network: the SSH tunnel is the only way in.

Set up the server

1. Install malac on the server.

   ssh devbox
   curl -fsSL https://raw.githubusercontent.com/lobirus/malac/main/install.sh | sh

   The script picks the Linux x86-64 release archive and puts malac and malac-control in ~/.local/bin; on other machines it builds from source. Add ~/.local/bin to your PATH if the script says so.

2. Add a provider on the server. Models, keys, MCP servers and plugins are the server’s configuration; the Mac needs none of it.

   printf '%s' "$LORA_API_KEY" | malac provider add lora \
     --base-url https://lora.example.com/v1 --model default --api-key-stdin --set-default

3. Keep the daemon running. By default the daemon exits after two idle hours. On a server, let it run:

   cat >> ~/.malac/config.toml <<'EOF'
   
   [daemon]
   idle_minutes = 0
   EOF

4. Get a project onto the server, for example by cloning a repository you work on:

   git clone <your repository> ~/src/app

5. Create a pairing code. This starts the daemon, which runs in its own session and keeps running after you log out.

   malac remote pair

   Pairing code  ABCDE-FGHJK   valid for 10 minutes, for one device
   
     (a QR code)
   
     scan it with a phone, or open http://127.0.0.1:7700/#pair=ABCDE-FGHJK
     SSH tunnel     malac remote add <name> http://127.0.0.1:7700 --pair ABCDE-FGHJK
   
   ! remote access is off: only this machine and SSH tunnels can pair and connect; `malac daemon restart --remote` opens it to other devices

   Remote access is off, and that is what you want here: through an SSH tunnel, the daemon sees requests that come from its own machine. Keep the code for the next part.

Pair the Mac

1. Open the tunnel. In a separate terminal tab on the Mac, forward a local port to the server’s daemon. Use a port other than 7700, which your Mac’s own daemon may use:

   ssh -N -L 7701:127.0.0.1:7700 devbox

   It prints nothing and keeps running. Leave it open while you work.

2. Save the connection with the code.

   malac remote add devbox http://127.0.0.1:7701 --pair ABCDE-FGHJK

   paired as macbook (3f2a9c1e) with malac 1.1.0 at http://127.0.0.1:7701
   saved `devbox`: malac 1.1.0 with 0 workspaces · `malac -C devbox` connects

   The Mac now has a device token of its own, in ~/.malac/connections.json. The code is used up.

3. Check the connection.

   malac remote list

   It lists devbox with its address and whether it answers.

Work on the server

1. Open the terminal UI on the server’s daemon.

   malac -C devbox

   It looks like a local session, with two differences: the header shows devbox › default, and the status line starts with @devbox. The choice is remembered, so a plain malac reconnects to devbox next time; malac -C local comes back to your Mac.

2. Open the project. Paths are the server’s, and a new tab starts in the server’s home folder:

   /cd ~/src/app

3. Give it something that takes a while, so there is something to come back to:

   run the whole test suite, fix what fails, and summarize the fixes

   Tool calls, approvals and subagents work as they do locally; the commands run on the server.

4. Leave. Press F10, or close the laptop. The agents keep working in the server’s daemon. Commands they start in the background, such as a dev server, keep running as jobs.

5. Come back. Open the tunnel again if it closed, and run malac. The tab is where you left it, with the agent’s answer, or a permission request waiting for you.

Instead of opening the terminal UI, you can also send a prompt straight away: malac -C devbox -p "what changed in the last commit?" prints the answer and exits.

Check in from a phone

A phone cannot use your SSH tunnel, so it needs a way to the server. Tailscale is the private option: if the server and the phone are on the same tailnet, turn remote access on and let malac run Tailscale Serve.

1. On the server, allow paired devices, keeping the daemon off the network:

   malac daemon restart --remote --host 127.0.0.1
   malac tunnel tailscale

   The restart is refused while agents or jobs run, so wait for the test run to finish. malac tunnel prints the tailnet address. The daemon stops the tunnel when it stops; set [remote] tunnel = "tailscale" and web.remote = true to have both on every start.

2. Create a code with malac remote pair. With the tunnel running, the QR code points to the tailnet address.

3. Scan it with the phone’s camera. The browser opens the web UI’s pairing form with the code filled in. Name the device and pair. The phone keeps its token and stays paired until you revoke it.

The web UI on the phone shows the same workspace and tabs, the transcript, the jobs, and the approvals waiting for you. The mobile apps will pair the same way.

Clean up

List the paired devices on the server and revoke the ones you no longer use:

malac remote devices
malac remote revoke <id>

A revoked device’s token stops working at once and its connections close. On the Mac, malac remote remove devbox forgets the connection and revokes its token when the server answers.

What you learned

• The daemon on a server holds the agents; clients pair once and connect with a device token of their own. See Remote access.
• An SSH tunnel needs no remote access at all, and exposes nothing.
• malac -C <name> points the terminal UI, the line mode and one-off prompts at a saved connection, and paths name the server’s files.
• malac tunnel gives the daemon an address that other devices can reach: Tailscale for your tailnet, Cloudflare or ngrok for a public one.