Skip to main content
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.
Sign in to each agent on that machine first. The server uses its logins and its permission settings: an agent set to allow everything there asks for nothing here either.

Set it up

1

Install it

On Linux (x86_64 or arm64), install arakun-server alone:
It puts the binary in ~/.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 sudo without a password; otherwise it prints the command to run.
  • Node.js 22, in ~/.local/share/arakun/node, linked as node, npm and npx in ~/.local/bin. Without Node, a new session fails as it starts.
  • Claude Code, in ~/.local/bin/claude, when there is no claude on the PATH. Run claude once 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’s PATH. 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 same origin) 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 git and gh logins.
  • The Explorer lists its files, and they open in file tabs (text only). @ in the composer completes its paths.
  • Fork, compact, rewind and /stage run on the server. “Continue with” hands the session to another agent on that server.
“New environment” makes a worktree on a server too: Alt+click the + and pick the machine, or right-click a server’s environment. It goes in ~/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>.
Set ARAKUN_GITHUB=readonly on the server, before service install, to keep it from pushing or opening pull requests.

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 sudo command 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 PATH of the shell you install it from, so it finds the same agents. If Node comes from mise or nvm, install it from a shell where node works. If you install an agent somewhere else later, run service install again.
On Windows there is no 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 is arakun-server-<folder>.

How devices reach it

--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.
What 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.