arakun server serve is Arakun without a window: for a build box, the workstation at the office or a VPS. It runs sessions of any agent signed in on that machine and keeps them going while nothing is connected. Agents ask for permission as they do in the app, and you answer from wherever you are.
arakun-server is the same server as a program of its own. It needs no display library.
Set it up
1
Install it
On Linux (x86_64 or arm64), install It puts the binary in
arakun-server alone:~/.local/bin. It checks the release’s checksums, and their signature when a verifier is installed.It also installs what the server runs agents with, if it is missing:- git and gh, with the system’s package manager. That needs root or
sudowithout a password; otherwise it prints the command to run. - Node.js 22, in
~/.local/share/arakun/node, linked asnode,npmandnpxin~/.local/bin. Without Node, a new session fails as it starts. - Claude Code, in
~/.local/bin/claude, when there is noclaudeon thePATH. Runclaudeonce to sign in.
--no-tools leaves all four to you. --version installs a given release.On a Mac or Windows, install the app and use arakun server in place of arakun-server.2
Start it
3
Pair a device
In another terminal:The link is good for two minutes and pairs one device. Use it in one of two ways:
- In the app: open the Servers tab and paste the link.
- On a phone, or in any browser: open the link. It is the page the phone remote uses: it lists the sessions, reads them live, and notifies you when one finishes or needs you.
4
Work with sessions
arakun-server help lists them all.Agents
Claude Code, Droid, OpenCode, Codex, Devin, Cursor, Antigravity and Workers AI, as in the app. Claude Code and Codex also need their ACP adapter. The server installs a missing one with npm the first time a session needs it, so Node 22 or newer must be on the server’sPATH. The install script puts one there.
In the app
Once paired, the app connects to the server when it starts. Each folder the server offers is an environment in the sidebar, marked with the machine’s name. A folder whose repository you also have here (the sameorigin) joins that project.
Its sessions open in the same tabs, with the same composer, as sessions here. Send, stop, approve and answer go to the server. In a server’s environment:
- The model menu lists the models and reasoning levels that server offers.
- A terminal is a shell in that folder on the server. The project commands from Settings run there too.
- The Changes panel shows that folder’s changes. Stage, discard, commit, pull, push and the pull request button run there, with the server’s
gitandghlogins. - The Explorer lists its files, and they open in file tabs (text only).
@in the composer completes its paths. - Fork, compact, rewind and
/stagerun on the server. “Continue with” hands the session to another agent on that server.
~/arakun-workspaces/<project>/<branch> there.
To spread new environments across machines, turn on Spread across machines in the Servers tab. A new environment then goes to the least busy connected machine that has the project, this computer included. Set each machine to Prefer, Normal or Avoid there.
To add a folder on a server, press the folder button on it in the Servers tab. Clone runs that machine’s git, with its logins. In the Marketplace, “Install on” adds a plugin or MCP server for Claude Code on a paired server.
“Forget” on a server in the Servers tab removes it, and has the server forget the app. If the server can’t be reached then, remove the app there with arakun-server unpair <device>.
Keep it running
service install runs serve as a service: systemd on Linux, launchd on macOS. It starts the server now, again after a crash, and at boot (Linux) or login (macOS).
arakun-server quit stops it until the next boot or login. service install --print shows the service file and installs nothing.
- Logged out (Linux). It keeps running after you log out, so you can set it up over SSH. If turning that on needs root, it prints the
sudocommand to run. - As root. Many VPSs only have root. There it installs a system unit that runs as root. The binary must then be in a folder only root can write to, such as
/usr/local/bin, not a home folder. To run the agents as another user, log in as that user and install from there. - macOS. Use
arakun server service install. It runs from login to logout, so a Mac nobody sits at needs automatic login. - Agents. The service gets the
PATHof the shell you install it from, so it finds the same agents. If Node comes from mise or nvm, install it from a shell wherenodeworks. If you install an agent somewhere else later, runservice installagain.
service command yet. To keep the server running, start arakun server serve from Task Scheduler, with the trigger “At log on”.
Update it
The server does not update itself. Run the install line again, then restart the service on the new binary:- Installed as root: the service is a system unit, so leave out
--user. - A server in another folder (
ARAKUN_SERVER_DIR): its unit isarakun-server-<folder>.
How devices reach it
- relay
- tailscale
- lan
--reach relay is the default. The server dials out, so it works behind a firewall, and everything between the device and the server is end-to-end encrypted. --relay <url> names a relay of your own.serve is started with is kept for the next run.
What it keeps
The server keeps its data in~/.local/share/arakun/server/, which only your user can read: paired devices, folders, sessions and their transcripts, and photos sent with prompts. The app’s own files are not touched, so the app and a server can run side by side. ARAKUN_SERVER_DIR names another folder, for a second server on the same machine.
A turn that is running when the server stops is cut off. Its session is still there after a restart, and the next message picks it up.