> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arakun.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Server

> Run Arakun without a window on a build box, an office workstation or a VPS, and follow its agent sessions from your other devices.

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

> [!TIP]
>
> 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:

```sh theme={"dark"}
curl -fsSL https://arakun.dev/install-server | sh
```

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](https://docs.arakun.dev/install.md) and use `arakun server` in place of `arakun-server`.

**2. Start it**

```sh theme={"dark"}
arakun-server serve   # runs until Ctrl+C, a signal or `arakun-server quit`
```

**3. Pair a device**

In another terminal:

```sh theme={"dark"}
arakun-server pair    # a link and its QR code
```

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](https://docs.arakun.dev/phone-remote.md) uses: it lists the sessions, reads them live, and notifies you when one finishes or needs you.

**4. Work with sessions**

```sh theme={"dark"}
arakun-server add ~/code/app                 # a folder sessions can start in
arakun-server new --agent claude "fix the failing test"   # prints its id
arakun-server ls                             # folders and sessions
arakun-server log <id>                       # its status and last entries
arakun-server wait <id>                      # until it stops working
arakun-server send <id> <text>               # a follow-up
arakun-server approve <id>                   # or deny: answer what it asks
arakun-server stop <id>                      # stop its turn
arakun-server devices                        # paired devices
arakun-server unpair <device>                # forget one
```

`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: <kbd>Alt</kbd>+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>`.

> [!TIP]
>
> 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).

```sh theme={"dark"}
arakun-server service install     # takes serve's flags: --reach, --port, --relay
arakun-server service status      # installed, running, lingering, and how it is reached
arakun-server service logs -f     # what it prints
arakun-server service uninstall   # stop it and remove the service; the data stays
```

`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:

```sh theme={"dark"}
systemctl --user restart arakun-server
```

* 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

> [tab] relay
>
> `--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.

> [tab] tailscale
>
> `--reach tailscale` serves it at the machine's tailnet name over HTTPS. It takes the machine's HTTPS port on the tailnet, so the app's Phone tab on Tailscale can't use it on the same machine.

> [tab] lan
>
> `--reach lan` listens on every interface over plain HTTP, on port 7474 unless you pass `--port`.
>
> > [!CAUTION]
> >
> > Nothing is encrypted, including diffs, commit messages and pull request text. Use it only on a network you trust.

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.