Guide

Set up a server by hand.

Set Up in Hewy does all of this in one tap. When it can't, say without sudo, on a locked-down server, or because you'd rather see every step, here's exactly what it does, and how to undo it.

The daemon
Node.js and agents
The sandbox
Removing it

What runs where. Everything below goes in your own account on the server, under ~/.local, except bubblewrap and Ubuntu's sandbox rule, which need an administrator. Nothing opens a network port. Hewy reaches the daemon over SSH, as you do. How Hewy works →

Which servers. Linux on 64-bit Intel, AMD or ARM (including a Raspberry Pi 4 or 5 with a 64-bit OS), Macs on Apple silicon or Intel, and Windows 10 and 11 PCs (64-bit Intel or AMD) with OpenSSH Server. On Windows, agents run while you're signed in to the PC, and without a sandbox for now. On other systems, Hewy gives you terminals, files and key management, but not agents.

The Hewy Daemon

One program that keeps your chats and terminals running on the server. Download the build for your server, and check it's the one Hewy released before you run it.

Find your build

uname -sm
# Linux x86_64   →  hewyd-x86_64-linux
# Linux aarch64  →  hewyd-aarch64-linux
# Darwin arm64   →  hewyd-aarch64-darwin
# Darwin x86_64  →  hewyd-x86_64-darwin

Download it, with its signed list of checksums

v=latest
f=hewyd-x86_64-linux    # yours, from above
base=https://hewy.ai/releases/hewyd/$v
curl -fLO $base/$f -O $base/manifest.json -O $base/manifest.json.sig \
     -O https://hewy.ai/guide/hewy-release.pub

Check the signature, then the checksum

The list is signed with Hewy's release key, which is kept offline. One line of manifest.json.sig must check out against it (the others are for test builds):

ok=no
while read -r s; do
  printf '%s' "$s" | base64 -d > sig.bin
  if openssl pkeyutl -verify -pubin -inkey hewy-release.pub \
       -rawin -in manifest.json -sigfile sig.bin >/dev/null 2>&1; then ok=yes; break; fi
done < manifest.json.sig
echo "Signed by Hewy: $ok"    # must say yes

grep -o "\"file\":\"$f\",\"sha256\":\"[0-9a-f]*\"" manifest.json
sha256sum $f    # on a Mac: shasum -a 256 $f
# The two must match.

The release key's fingerprint, as base64: dvbu7hkDRYIjLAF6Y1B5rKeryENAoVtVOr8eeiGLZ/k=. It's the same key the Hewy app is built to trust.

Install it

mkdir -p ~/.local/bin
install -m 755 $f ~/.local/bin/hewyd
~/.local/bin/hewyd --version

Keep it running

On Linux with systemd, as a user service, so it starts with the server:

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/hewyd.service <<'EOF'
[Unit]
Description=Hewy Daemon (keeps your AI agent sessions running)
After=network-online.target

[Service]
ExecStart=%h/.local/bin/hewyd serve --wait
Restart=on-failure
RestartSec=2

[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now hewyd.service

To keep it running after you log out (Set Up's "Keep agents running after you log out"):

loginctl enable-linger "$(id -un)"   # or, if refused: sudo loginctl enable-linger "$(id -un)"

On a Mac, Hewy installs a LaunchAgent, ~/Library/LaunchAgents/ai.hewy.hewyd.plist, that runs ~/.local/bin/hewyd serve --wait while you're logged in to the desktop. Without it, the daemon starts when Hewy connects.

Without systemd (Alpine, some containers), nothing else is needed: Hewy starts the daemon when it connects, and it runs until the server restarts.

Node.js and the agents

Claude, Codex and OpenCode's connectors are Node.js programs. They need Node.js 22 or newer. If node --version says so already, skip ahead.

Node.js, for your account only

Set Up uses Node.js 22.22.1 from nodejs.org, checked against its published checksum, unpacked into ~/.local:

n=node-v22.22.1-linux-x64        # or -linux-arm64, -darwin-arm64, -darwin-x64
curl -fLO https://nodejs.org/dist/v22.22.1/$n.tar.gz
curl -fsSL https://nodejs.org/dist/v22.22.1/SHASUMS256.txt | grep " $n.tar.gz\$" | sha256sum -c
tar -xzf $n.tar.gz -C ~/.local --strip-components=1
~/.local/bin/node --version

On Alpine, use the system's: sudo apk add nodejs npm.

The agents

With the daemon and Node.js in place, Hewy installs each agent from the server's page (Agents → Install), inside the sandbox. By hand, the same packages and versions:

npm install --global --prefix ~/.local @agentclientprotocol/claude-agent-acp@0.89.1   # Claude
npm install --global --prefix ~/.local @agentclientprotocol/codex-acp@2.2.2           # Codex
npm install --global --prefix ~/.local opencode-ai@1.19.0                             # OpenCode

Then add your API keys in Hewy, or sign in with your Claude or ChatGPT plan from the server's page. Keys live in ~/.config/hewy/agents.env, readable only by you, and agents in the sandbox can't read the file.

The sandbox

On Linux, agents run inside bubblewrap, which keeps them away from the daemon, its settings and your API keys, while they work on your files. It needs an administrator to install, once.

Install bubblewrap

sudo apt-get install -y bubblewrap        # Debian, Ubuntu
sudo dnf install -y bubblewrap            # Fedora, RHEL
sudo apk add bubblewrap                   # Alpine
sudo pacman -S --noconfirm bubblewrap     # Arch
sudo zypper --non-interactive install bubblewrap   # openSUSE

Ubuntu 23.10 and 24.04

These releases block the kernel feature bubblewrap needs, unless a rule allows bubblewrap. Ubuntu 24.10 and later ship that rule; for the two before, Set Up adds Ubuntu's own:

curl -fLO https://hewy.ai/guide/hewy-bwrap
sudo apparmor_parser -r hewy-bwrap
sudo install -m 644 hewy-bwrap /etc/apparmor.d/hewy-bwrap

It lets bubblewrap create sandboxes, and everything bubblewrap starts runs without extra privileges, so it can't be used to get round Ubuntu's restriction.

Check it

Reconnect in Hewy: the server's page says "Agents run in a sandbox (bubblewrap)", or why not. In a container, the container's host has to allow it; the page says what to change.

To run agents without the sandbox on one server, even where it works, turn off Sandbox agents on its page. bubblewrap stays installed.

Removing it

In Hewy, a server's page lists what Hewy installed, each with Remove, and "Remove Hewy from This Server…" takes the daemon away in one go. By hand:

# The daemon, its service, its settings and keys, and (last line) chat history
systemctl --user disable --now hewyd.service; rm -f ~/.config/systemd/user/hewyd.service
rm -f ~/.local/bin/hewyd
rm -rf ~/.config/hewy
rm -rf ~/.local/state/hewy

# The agents
npm uninstall --global --prefix ~/.local @agentclientprotocol/claude-agent-acp @agentclientprotocol/codex-acp opencode-ai

# Node.js, if Set Up put it in ~/.local
rm -f ~/.local/bin/{node,npm,npx,corepack}; rm -rf ~/.local/lib/node_modules/{npm,corepack} ~/.local/include/node

# The sandbox, as an administrator
sudo apparmor_parser -R /etc/apparmor.d/hewy-bwrap; sudo rm -f /etc/apparmor.d/hewy-bwrap
sudo apt-get remove -y bubblewrap   # or your distribution's equivalent

# Keep-running-after-logout
loginctl disable-linger "$(id -un)"

On a Mac, the service is launchctl bootout "gui/$(id -u)/ai.hewy.hewyd" and rm ~/Library/LaunchAgents/ai.hewy.hewyd.plist.

Rather not type all that?

Set Up does every step for you, and shows each command first.