Updates

Update your computer while keeping your edits.

Updates run only when you or your agent run empty computer update. Run it on the computer through a Full access MCP connection, or from the workstation client. Home shows when a newer release exists and gives your agent instructions for both paths. Opening Home never starts an update.

$ empty computer update --check
Checking computer yourname to EmptyOS 0.1.7
Catalog: https://release.emptyos.com/emptyos/v1/catalog.json
# ... (artifact, digest, and the updater's inspection)

Continue this exact EmptyOS release with:
  empty --computer yourname computer update --resume stage.A1b2C3

$ empty --computer yourname computer update --resume stage.A1b2C3
Resuming computer yourname update from stage.A1b2C3
# ...

Choose an update command

Before checking or applying an update from a workstation, check its client:

empty --version
npm view @emptyos/client version

The client version is separate from the computer's EmptyOS release, which empty status shows. If the client is older than the version on npm, run npm install -g @emptyos/client@latest, then empty --version again to confirm that the command uses the new client. If the npm lookup or install fails, or the command still uses the older client, report the exact output and resolve client setup before continuing the update. The next empty command refreshes registered agent skill copies. If it prints a skill refresh notice, have your agent read the named SKILL.md again before continuing. These client steps run on the workstation, not through the computer's MCP connection.

Choose whether to inspect a release first or apply it now:

• empty computer update --check inspects the computer, retains the exact signed release and plan, and prints the resume command. It writes staging but activates nothing.
• empty computer update selects the current catalog release and applies it.
• empty computer update --resume <stage> applies exactly the checked release, even if a newer one has appeared since.
• --json works on all of them. From the workstation, use --computer <alias-or-url> to select the intended computer. The command inside the computer takes no selector.

Update through an assistant connection

Confirm the computer with get_status. Use Full access start_command to run empty computer update with timeout_seconds: 600, then poll read_command with the same operation_id. These commands run on the EmptyOS computer. The assistant's own sandbox is separate.

Keep the retained stage printed before installation. Recovery can restart while the detached update continues. Reconnect and read the original command. If the result is updating with exit code 75, wait and use the printed empty computer update --resume <stage> command. Resume checks for a running transaction before starting recovery.

An older resident CLI may lack computer update. Check with empty computer update --help. Use the official workstation client once to install a release that includes the resident command. Do not clone the development repository to perform the update.

What an update changes

An update replaces Home, Gateway, the resident empty CLI, EMPTY.md, and the resident skills in ~/emptyos as one commit. That commit appears in Changes as read-only history. The update also replaces Recovery and the emptyos-* system services. It never writes ~/things, ~/projects, or ~/data. It does not upgrade the Linux distribution.

empty status shows the installed EmptyOS version. empty --version shows the workstation client version, a separate number.

Resolve conflicts with your edits

Your platform files are editable, so an update can overlap your edits. The updater replaces files you did not touch. It keeps files you changed that the release did not change. When you and the release changed the same file, the command stops with needs-reconciliation. It keeps a separate candidate, lists the conflicting paths, and prints the resume command.

To resolve the conflicts, have your agent follow these steps:

1. Use the computer's Full access MCP connection, or enter it from the workstation with empty ssh.
2. Read RECONCILE.md in the retained stage. The --json result gives that path and the candidate's path.
3. Edit only the listed paths in the candidate.
4. Run the printed resume command.

Before installation, resume checks that nothing else changed and that the platform tests pass. What you can change explains how the updater compares three versions of each file.

If something goes wrong

Use the command output to choose the next step:

• A dropped connection leaves a retained stage. Run the printed continuation or recovery command rather than starting a new update.
• computer-busy means another change holds the lock. Retry.
• updating with exit code 75 means the detached transaction is still running. Keep its stage and wait before resuming.
• If the workstation reports an invalid release, complete the client check above before concluding that the release is broken. An older client can reject files allowed by a newer release. Then retry the failed check. For an approved apply, continue any retained stage with its printed resume command instead of starting a new update. Client setup does not authorize applying a checked release. Never bypass signature, digest, or file-scope checks. If the current client still rejects it, report the client version and exact error.
• Older computers may need a one-time operator update first. The command says when this is required.
• Updates refuse an older version. A bad release is corrected by a newer one.