# A NAS as a machine

A NAS that runs Debian underneath (UGREEN's UGOS Pro, for one) can be an always-on Andon machine. It is a Linux
machine ([Linux machines](https://andon-docs.pages.dev/machines/linux.md)) with three differences: the vendor owns the system packages, the board may be on
your own computer, and the NAS may need its own route to a board it also hosts.

## Install the tools in your home folder

On a NAS, `apt` may already be broken (`apt --fix-broken` wants to remove the vendor's own packages), firmware updates
can replace what you install, and `sudo` asks for a password. Install what Andon needs under `~/.local` instead, with no
root:

```sh
# Node 22 from nodejs.org, checked against its SHASUMS256.txt, linked into ~/.local/bin
mkdir -p ~/.local/opt ~/.local/bin && cd ~/.local/opt
V=v22.x.y   # the current v22 release
curl -fsSLO https://nodejs.org/dist/$V/node-$V-linux-x64.tar.xz
curl -fsSL https://nodejs.org/dist/$V/SHASUMS256.txt | grep " node-$V-linux-x64.tar.xz\$" | sha256sum -c -
tar -xJf node-$V-linux-x64.tar.xz && ln -sfn ~/.local/opt/node-$V-linux-x64 ~/.local/opt/node
for b in node npm npx; do ln -sf ~/.local/opt/node/bin/$b ~/.local/bin/$b; done

# git, tmux and gh from conda-forge with micromamba (one static binary)
curl -fsSL -o ~/.local/bin/micromamba https://github.com/mamba-org/micromamba-releases/releases/latest/download/micromamba-linux-64
chmod 755 ~/.local/bin/micromamba
MAMBA_ROOT_PREFIX=~/.local/share/mamba ~/.local/bin/micromamba create -y -n tools -c conda-forge git tmux gh
for b in git tmux gh; do ln -sf ~/.local/share/mamba/envs/tools/bin/$b ~/.local/bin/$b; done

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
```

Put `~/.local/bin` first on your `PATH` before you run the installer. The service runs the `node` the installer finds,
with your `PATH`, so a system `node` older than 22 must not come first.

Then sign in to GitHub and Claude Code. Each prints a link and a code to finish in a browser on another device:

1. `gh auth login --web`, then `gh auth setup-git`. Git then clones private repositories over HTTPS with gh's token,
   so the NAS needs no SSH key of its own on GitHub.
2. `curl -fsSL https://claude.ai/install.sh | bash` installs Claude Code into `~/.local/bin`; `claude auth login` signs
   it in.

## Reach a board on your own computer

`andon up` listens on `127.0.0.1` and, when that computer is on a tailnet, on its tailnet address too. It looks for the
tailnet once, when it starts: run `tailscale up` first, or restart `andon up`. Put the NAS on the same tailnet.

If the NAS has no Tailscale package, run Tailscale in Docker on the host network, starting `tailscaled` directly (the
image's default entrypoint drops an interactive login after 60 seconds):

```sh
docker run -d --name tailscale --restart unless-stopped --network host \
  --cap-add NET_ADMIN --cap-add NET_RAW --device /dev/net/tun:/dev/net/tun \
  -v tailscale-state:/var/lib/tailscale --entrypoint tailscaled \
  tailscale/tailscale:<pinned version> --state=/var/lib/tailscale/tailscaled.state --socket=/var/run/tailscale/tailscaled.sock
docker exec tailscale tailscale up --hostname=<name> --timeout=3s   # prints the login link; approve it once
```

The login survives restarts. If you delete the device in the Tailscale admin console, it is logged out for good
(`node not found` in `docker logs tailscale`): run `tailscale logout`, then `tailscale up` for a new link.

Then install from the board's tailnet address:

```sh
curl -fsSL http://<tailnet address>:8787/install.sh | sh -s -- --no-browser --no-install-claude
```

## When the NAS hosts the board too

When the server runs in Docker on the NAS, published on `127.0.0.1:8787` and on the tailnet with `tailscale serve`, the
NAS can't reach its own tailnet name: Tailscale in a container doesn't feed the NAS's DNS. Point the agent at the local
port:

1. In `~/.config/andon/config.json`, keep `boardUrl` as the HTTPS address. Links in pull request comments and the board
   terminal use it.
2. Set `apiUrl` to `http://127.0.0.1:8787`.
3. Run `systemctl --user restart andon-agent.service`.

Self-updates still fetch from `boardUrl`, so they fail on that NAS until it can resolve the name. `andon update` needs
the same fix.

## Choices to make on purpose

- **Policy preset.** With `--yes`, the machine gets **Open**: any org recipe, auto merge and new repositories.
  Pass `--preset standard` (or `locked`) if the NAS should be more careful than your laptop.
- **Runs at once.** A machine starts at 3 concurrent runs. A NAS with a few GB of memory free does better at 1 or 2:
  open **Settings → Machines**, press **Edit** (the pencil) on the NAS, and set **Max concurrent runs**.
- **Home folder permissions.** Vendors often leave home folders writable by everyone, which lets anyone on the box add
  an SSH key or swap the agent's config. Run `chmod 700 ~/.ssh ~/.config/andon` and
  `chmod 600 ~/.ssh/authorized_keys`, and tighten the home folder itself as far as the vendor's file sharing allows.
- **The board terminal.** A board you built yourself may carry the terminal helper only for your own platform. Then
  `andon doctor` reports no terminal helper for `linux-x64`, and the board terminal won't open on the NAS. Runs still
  work. See [Agent updates](https://andon-docs.pages.dev/machines/updates.md#the-terminal-helper).

## Check it after a reboot

Linger should start your user's services at boot. On some NAS systems it doesn't: `journalctl --user -b` begins at
the first SSH login, and the agent stays offline until then. Reboot once and look for the machine on the board before
you rely on it.

If setup stops with `andon: fetch failed` after you approve, the approval is kept but not used. Run `andon setup` again
and approve the new code.
