Using VyreDraft

Box care

Your box is the always-on server that runs Vyre. On a Linux server it is a Docker Compose stack in /srv/vyre with the vyre container, and its data in Docker volumes. You look after it from your Mac with vyre box ..., which runs each step over SSH so you never open a shell on the server, or on the server itself with the host's vyre command. This page covers the care tasks. What each folder and volume holds, and who can reach the box, is in The box and the Mac.

Check on it#

vyre box       # the box's address and SSH target, and whether it answers from here

  your box  https://alex.vyre.run · [email protected]
  answering · 0.0.1

vyre status    # running or not, version, role, how many modules started
vyre modules   # each module, and the error of any that failed

  vyred running · 0.0.1 · box · pid 7 · up 5312s
  17 modules running

On the server, the host's vyre is a small shell script, /usr/local/bin/vyre. It runs every command in the vyre container, except three it handles itself: vyre up starts the stack if it is not running, waits up to a minute for Vyre, then prints the setup link or your address; vyre update upgrades (below); vyre logs follows Vyre's output.

If this happens

vyre box says "no box yet: vyre box add user@host"#

The vyre box commands work only for a box this Mac knows the SSH target of. If you installed the box with the curl installer on the server, run vyre box add [email protected] once: it finds Vyre already there and carries on from where it stands.

If this happens

vyre box says "not answering from here"#

This Mac cannot reach your box, or the box is down. Check the box with vyre status on the server, and run vyre doctor on the Mac for the path and the relay.

Read its logs#

On the box:

vyre logs      # follow Vyre's output (docker compose logs -f vyre)

Vyre also writes a log file per day, ~/.vyre/logs/YYYY-MM-DD.log. On a Docker box that is /home/vyre/.vyre/logs/ inside the vyre_vyre-home volume.

Cap what it spends#

Vyre keeps one ledger of what sessions, agents and memory spend, per provider and per day (UTC). Some figures are estimates, which the list marks, because they are tokens times a price rather than a cost the provider reported. A daily cap per provider stops the spending without asking you on every call.

vyre spend                      # today's spend per provider against its cap
vyre spend raise claude 20      # cap Claude at $20 a day
vyre spend raise claude +5      # add $5 to the cap
vyre spend raise all 50         # one cap over every provider together
vyre spend raise claude off     # no cap

At the cap, the thread that was spending is paused with one line that says what happened and the command to raise the cap, and memory answers from facts and search until the next UTC day or until you raise it. A provider with no cap has none. The Vyre app shows the same list under Settings, Spending limits, with Change cap for each one.

Upgrade#

vyre update

vyre update brings the box to the newest release. It asks GitHub Releases for vyre-ai/vyre: stable (the default) is the newest release that is not a prerelease, and beta is the newest of either. A stable box never takes a prerelease, such as 0.2.0-rc.1: only a box you set to beta would. Pick one with vyre update --channel beta or VYRE_CHANNEL=beta, or a release by version with --to 0.2.0. While GitHub has no release yet, or when you set VYRE_BOX_URL yourself, it uses the site instead (https://vyre.run/box/ by default), as it always has.

To look without changing anything, run vyre update --check on the server. It says which version an update would install and from which channel, and whether the server already runs it. It exits 0 when the server is current and 1 when a newer release waits. vyre update --check --json prints one line, { "current", "channel", "latest", "update", "source" }. It downloads nothing but the release list, and writes nothing. When the server already runs the newest release, vyre update says "already on" that version and stops: it does not restart the server. vyre update --reinstall puts the same version on again anyway.

Vyre looks for a newer release once a day and keeps the answer, so Settings can say "Update available" and show what changed. On a server set up by the install line, Settings also has an Update to 0.x button. It does not run anything itself: it drops a one-line request into /var/lib/vyre-update/request, a folder that only Vyre can write to and that root owns along with every folder above it, and a small systemd unit on the host (vyre-update.path, owned by root) runs vyre update for it. That update never accepts --allow-unsigned, never goes back to an older version than the newest this server has had (a version the host keeps in a file only root writes), waits at least ten minutes between updates, backs up your data first, and puts the old version back on its own if the new one does not start. The card shows each step and the result. The command above always works too, and a server with no systemd shows only the command.

Turn on Update automatically in Settings (off by default) and Vyre asks for a new release by itself between 2 and 5 in the morning, once per version, the same way. The channel is the host's own: set VYRE_CHANNEL=beta in the server's .env, or leave it on stable. Set auto to "off" inside the update object in config.json to stop the daily look. On a Mac there is no update button: run vyre update (see Update Vyre on a Mac, below).

Updates are signed. Every file comes from the release and is checked against its SHA256SUMS before anything on the box changes. The SHA256SUMS list itself is checked against its Ed25519 signature (SHA256SUMS.sig) from Vyre's release key, which is built into the vyre command. An unsigned or badly signed release is refused, and vyre update --allow-unsigned installs it anyway after a plain warning that nothing proves it came from Vyre. The same holds for vyre update on a Mac. A box that pulls its image instead of building it also checks every Vyre image of the release with cosign against the release workflow's identity, and refuses to pull one it cannot check. Then, in order:

1. It backs up the database with vyre backup, into /home/vyre/.vyre/backups/pre-<version>.tar.gz in the container, with a copy in /srv/vyre/backups/ that only you can read. It is sealed like any vyre backup file and holds the sealed vault, so treat it like the vault.
2. It tags the image that runs now as vyre:prev, and keeps the box files as they are in /srv/vyre/box.prev/.
3. It refreshes the box files (compose.yml, compose.build.yml, vyre.env.example, Dockerfile, dockerignore) from the release. .env and vyre.env are never touched.
4. When /srv/vyre/.env lists compose.build.yml in COMPOSE_FILE and VYRE_SOURCE is /srv/vyre/src, it swaps in the new vyre.tgz and keeps the old one as /srv/vyre/src.prev, then rebuilds the image with fresh base images. Otherwise it pulls the new image.
5. It recreates what changed and waits up to a minute for Vyre. A server that has not answered yet but is still working (its log moved in the last 20 seconds) is waited for, up to ten minutes in all, since setting up the Records types after a restart can take that long.

If Vyre does not come up in that time, or goes quiet without answering, the update undoes itself: the old source, the old image, the old box files and the database from step 1 all go back, and vyre update exits 1 saying it rolled back. Store migrations only go forward, which is why the database comes back from the backup. That means anything written between the backup and the rollback (a chat, a note, a setting) is lost, and the update says so as it rolls back. A slow start that is still working is waited for, so a rollback should be rare; if one happens, check vyre logs before you try again.

The automatic updater also keeps a floor, the newest version this server has had, and refuses anything older. After an update that rolled back following its publication, the floor can sit above the version that runs; that blocks only older releases, never the forward update. sudo vyre raise-floor raises it to the version installed here after an update you ran yourself, and takes no version. Once an update has come up healthy, nothing restores the database on its own, so nothing you write after that is lost.

After a healthy update, when the release carries an Android build, it brings the phone app along: it checks the APK and android.json against SHA256SUMS, copies the APK into /home/vyre/.vyre/releases/android/, then android.json last (the old one stays as android.json.prev), and runs vyre call releases.sign. If signing refuses (no_release or release_mismatch), the update says so and still succeeds. A release without an Android build leaves the folder alone. Last, it replaces the vyre command itself with the release's copy, and prints what vyre up prints.

Your volumes carry over, and each module migrates its own data at start (Specification, Section 7.1).

To go back by hand:

vyre update --rollback

It puts the previous source, image, box files and phone app manifest back, and keeps the database as it is now. Run it again to go forward. To put the database from before the update back too:

vyre update --rollback --restore-data

That drops everything written since the update, so it says what it would drop and asks you to type restore. Off a terminal, pass --yes instead.

The image carries the Claude Agent SDK that Vyre's own sessions run on, with the Claude Code it bundles, in /opt/vyre-sessions-sdk (ADR 0030). The box never downloads it at runtime. Its version is pinned as VERSION in core/sessions/sdk-pin.js: a bump there rebuilds the image, and vyre update brings it in like any other change.

vyre update refreshes the box files and the wrapper. Running the installer again does too, and it also leaves .env and vyre.env alone:

curl -fsSL https://vyre.run/install.sh | sh

Update Vyre on a Mac#

On a Mac, or any machine where you installed Vyre with npm, vyre update updates Vyre itself:

vyre update --check    # is a newer release out? exit 0 when current, 1 when one waits
vyre update            # show what changed, then install it

  0.1.0 → 0.2.0 · stable

  0.2.0
    what 0.2.0 changed

  Update to 0.2.0 now? (y/N) y
  updated 0.1.0 → 0.2.0 · vyred answering

It reads the releases of vyre-ai/vyre on GitHub and shows the notes of every release between the version you run and the new one. When you say yes it:

1. backs up your data into ~/.vyre/backups/pre-<version>/;
2. downloads the release into ~/.vyre/releases/<version>/ and checks every file against the release's SHA256SUMS, so a damaged or wrong download stops it before anything changes;
3. installs it with npm install -g, restarts Vyre the way vyre up does after an upgrade, and waits for Vyre to report the new version.

If Vyre does not come back on the new version, vyre update puts the previous version back, restores the backup, and says it rolled back. Once the new version has answered, it never touches your data again on its own.

--restore-data drops everything written since that backup, so it says the backup's date and asks you to type restore. With --json, or with no terminal, it needs --yes instead. ~/.vyre/releases keeps the two newest releases and the one you run.

If this happens

"this vyre runs from a checkout; update it with git"#

You run Vyre from a clone of the repository, not an npm install. Run git pull, then vyre up.

If this happens

"0.3.0 updates only from 0.2.0 or newer"#

A release sometimes needs an older one in between. Run the command it names, for example vyre update --to 0.2.0, then vyre update again.

On a box, the host's vyre update (above) does the job; inside the box's container, vyre update says so and stops.

Run the installer by hand#

vyre box add from the Mac runs the installer for you. On the server you can run it yourself:

curl -fsSL https://vyre.run/install.sh | sh

It is scripts/install-box.sh. It is safe to run again: every run converges on the same state. Pass options after sh -s --, for example curl -fsSL https://vyre.run/install.sh | sh -s -- --dry-run.

What it does, in order:

1. Checks this is Linux. On a Mac it prints a hint and stops.
2. Checks for Docker with Compose 2.24 or newer. If Docker is missing it asks before running curl -fsSL https://get.docker.com | sh; with no terminal to ask on, or a no, it prints the command and stops. An old Compose gets the same kind of message and a stop.
3. Picks how to get the image: it pulls VYRE_IMAGE when the registry has it, and otherwise builds from vyre.tgz.
4. Downloads SHA256SUMS, then compose.yml, compose.build.yml, vyre.env.example, the host wrapper and, for a build, vyre.tgz, and checks each against its line. A missing line or a different hash stops the install before anything is written. With --from DIR the files come from the checkout instead.
5. Creates /srv/vyre, owned by you (the account that ran sudo, if you did), writes the box files into it, and unpacks vyre.tgz into /srv/vyre/src for a build.
6. Writes /srv/vyre/.env (mode 0600) with COMPOSE_PROJECT_NAME=vyre, COMPOSE_FILE (plus VYRE_SOURCE for a build) and DOCKER_GID, the group that owns the Docker socket. It writes the file only if it is not there. The one change it makes to an existing .env is to add DOCKER_GID when the line is missing.
7. Installs the host wrapper to /usr/local/bin/vyre. If something else already has that name, it asks first.
8. Runs vyre up, or vyre up --print-link with --print-link.

sudo is used only for Docker's own install, for /srv/vyre when /srv is root's, and for /usr/local/bin/vyre. If your account cannot reach Docker, the installer runs the stack through sudo and says so; from then on the host's commands need sudo vyre.

If this happens

"Docker is installed but not running."#

Start it with sudo systemctl start docker, then run the installer again.

If this happens

"checksum mismatch for ..." or "SHA256SUMS is not a checksum list"#

Nothing was installed. The download was damaged, or VYRE_BOX_URL points somewhere that is not a Vyre release. Unset VYRE_BOX_URL and try again.

Back up#

There are two kinds of backup.

Vyre's own data, taken while Vyre runs, on the box:

vyre backup                  # vyre-backup-YYYY-MM-DD.vyre in /home/vyre, asks for a passphrase

It asks for a passphrase twice (12 characters or more) and seals the file with it: there is no unencrypted backup, and the file opens only with that passphrase. It holds config.json, a consistent copy of the store (taken with SQLite's VACUUM INTO while Vyre writes), vault/, watchers/, modules/, certs/, names/ and data/ (your artifacts), the Drive of every Space on the box (your documents and each project's files, still sealed), plus your project files (the box's /work) and your session transcripts. Add --skip-projects if your projects live in git or Drive, and --skip-transcripts to leave the transcripts out. It leaves out models/, logs/, the socket and the pid file, and your Claude, Codex and Grok sign-ins: sign in again after a restore, or pass --with-provider-logins to carry them. An unfinished backup resumes when you run the same command again. The file lands in /home/vyre, inside the vyre_vyre-home volume. Copy it off the box:

cd /srv/vyre && docker compose cp vyre:/home/vyre/vyre-backup-2026-09-27.vyre .

The Space's members, grants and sealed values come back too, once you have given your recovery code a single time (the spaces.bundle.enrol tool, or ask your assistant to set up the Space bundle). From then on Vyre writes space-bundles/<space>.vyb into the home by itself, every hour, with no further asking, and every vyre backup carries the folder. Every Space on the box has its own bundle and its own owner's code: a team's Space is turned on by its owner (Settings, Backups), and until then that screen says plainly "Space Harbor isn't backed up: its owner hasn't turned on backups." A bundle holds the Space's id, its members and grants, a copy of its store (for a team's Space), and each sealed value (an SSN, a bank number) sealed under a key that only that owner's recovery code opens. None of the old box's own keys is in it, and nothing in it is readable without the code.

On a fresh box, restore the backup and the Space in one step:

vyre restore vyre-backup-2026-10-10.vyre --force --recovery-code <your code>

If the box holds Spaces with different owners, vyre restore asks for each owner's code in turn (Enter leaves one for later), brings back every Space it has a code for, and names the rest.

The Space keeps its id, so every link and record reference still works. Its sealed values are sealed again under the new box's own keys. Your members are back with their roles, and the log says the Space was restored and from what point. What a member sealed on their own device (their vault, their chats' keys) is carried as ciphertext, never re-keyed: it opens again when that person's device next connects to the restored Space. The old log itself is not carried, only where it ended.

Everything, Claude Code's sign-in and transcripts, and your projects in /work, from the Mac:

vyre box backup                         # vyre-box-backup-YYYY-MM-DD.tar.gz here
vyre box backup ~/Backups/box.tar.gz

The box is stopped while this runs: it stops the stack, copies the vyre-home and vyre-work volumes into one file on your Mac (mode 0600), and starts the stack again, even if the copy fails or you press Control-C. --force replaces an existing file.

Both files contain your sealed vault. Keep them somewhere only you can read. The vyre backup file is already sealed with its passphrase; encrypt the vyre box backup file yourself (age -r <key> file).

Restore#

A vyre backup file goes back with Vyre stopped. Vyre is the container's main process, so restore runs in a one-off container:

cd /srv/vyre
docker compose cp vyre-backup-2026-09-27.vyre vyre:/home/vyre/
docker compose stop vyre
docker compose run --rm vyre vyre restore /home/vyre/vyre-backup-2026-09-27.vyre --force
vyre up

Restore asks for the backup's passphrase. Without --force, it refuses to replace a store the box already has. It also refuses an archive with paths outside the known folders, or with links in it.

The backup carries the artifacts your agents made (data/artifacts: every version, a dashboard's data, a deck's images, and the archive and 30-day undo state). A restore swaps them in by moving the box's current artifacts folder aside first and deleting it only once the new one is in place, so a failed restore keeps what was there. If the power fails between those two steps, a folder named .artifacts.old-<number> is left under data/; it is safe to delete once you have checked that your artifacts are there. Public links come back as they were when the backup was made: a link that was on then is on again.

A vyre box backup file holds the two volumes as folders (vyre-home/ and vyre-work/). To put it on a server that has no Vyre volumes yet, install without starting, create the volumes the way Compose would, unpack into them, then start:

curl -fsSL https://vyre.run/install.sh | VYRE_NO_UP=1 sh
for v in vyre-home vyre-work; do
  docker volume create --label run.vyre=1 --label com.docker.compose.project=vyre \
    --label com.docker.compose.volume=$v vyre_$v
done
docker run --rm -i -v vyre_vyre-home:/b/vyre-home -v vyre_vyre-work:/b/vyre-work \
  alpine:3.20@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc tar xzf - -C /b < vyre-box-backup-2026-09-27.tar.gz
vyre up

Start the old server's stack again only after you have taken Vyre off it: two boxes with one identity fight over it. To go from one live server to another, vyre box move (next) does all of this for you.

Move to another server#

From the Mac:

vyre box move [email protected]

It installs Vyre on the new server, stops the old stack, streams the two volumes from old to new through your Mac, starts the new one, and waits for it to answer at the same name and address. Once the new box answers, Vyre is taken off the old server, whose volumes stay until you delete them.

The new server must not already hold a box or Vyre volumes. If anything fails after the old stack stops, the move stops the new one and starts the old one again, and says which.

Agents' computers#

Agents' computers run as their own containers through Vyre's Docker proxy. It runs on every Vyre server from the install: the vyre command names the computers profile itself, so there is nothing to add to /srv/vyre/.env.

What the proxy allows is in The box and the Mac.

Remove it#

A server holds no name of its own: the name belongs to your space. Removing the server does not free the name; take the server off the space in the Vyre app if you want it to stop serving the name.

vyre box remove           # stop the stack, remove /usr/local/bin/vyre, keep the volumes
vyre box remove --purge   # also delete the volumes, after the server asks

curl -fsSL https://vyre.run/install.sh | sh -s -- --uninstall
curl -fsSL https://vyre.run/install.sh | sh -s -- --uninstall --purge

Both run docker compose down in /srv/vyre and remove /usr/local/bin/vyre. Without --purge, the volumes and /srv/vyre stay, so a reinstall picks up where it left off. --purge lists every volume labelled run.vyre=1 in project vyre and, after you say yes, deletes them: the vault, Claude's sign-in, the store and /work. /srv/vyre stays either way, with its .env; remove it with sudo rm -rf /srv/vyre. The installer never removes Docker, and leaves the images (docker image rm them if you like).

On the Mac, vyre down && npm rm -g vyre removes Vyre and leaves ~/.vyre.

A box without Docker#

A Linux box installed from npm with systemd units is upgraded with sudo npm install -g https://vyre.run/box/vyre.tgz && vyre up, and removed with sudo vyre uninstall --system && sudo npm rm -g vyre (--purge also deletes the data). See Without Docker.

Next#

• The box and the Mac: what runs where, the folders and volumes, and who can reach the box.
• Troubleshooting, when something does not start.
• CLI reference, every vyre box form.

What root runs, and what it reads#

Updates that run as root (the automatic path from Settings and sudo vyre update) never read a file you or an agent on your account can write as configuration. Root starts compose from its own copies of the released compose.yml, in a folder only root can write, with a root-written env file and every file, project and folder named explicitly. It refuses an override file or a COMPOSE_* setting, takes how the box is built (pulled, built from the released source, or from your own checkout) from a record it made when the updater was installed, and checks every ghcr.io/vyre-ai image of a release with cosign before pulling. sudo vyre up and the other root commands use the same copies once the updater is installed. A host with no updater (no systemd) keeps the stack folder's files, as the installer laid them down.

One thing no script can fix: if your account may run sudo without a password, anything running as you can already become root, and none of this protects you from it. Keep sudo asking for a password on a box where agents run as your account.

Being in the docker group is equivalent to root on that host, so only the owner should be in it. The installer's own first vyre up runs as you, straight after it lays down the files it just verified; root's copies exist from the next step, when the updater is installed.