Back up and move your server

Keep the data directory and its server version together. It contains agent definitions, revisions, run history, files, learning, and sealed credentials. The key that decrypts saved credentials lives separately and needs its own protected backup.

Make a consistent backup

1. Record the launcher/server version and the --data path. The published launcher defaults to ~/.agentrun.
2. Let active runs finish and prevent new submissions. Check for surviving run processes before copying data; stopping only the browser does not stop execution.
3. Stop the server and ensure it and its run processes are no longer writing.
4. Copy or snapshot the whole data directory, including hidden files, SQLite WAL files, and learning repositories. Preserve permissions.
5. Back up the sealing key separately through your secret manager. If you set AGENTRUN_SEAL_KEY, preserve that value securely. Otherwise the launcher stores it at $XDG_CONFIG_HOME/agentrun/seal.key, or ~/.config/agentrun/seal.key. Do not print it or include it in a shared backup.
6. Store the data backup securely too: it includes the server token and owner-session settings.

Do not copy only store.sqlite, omit companion WAL files, or copy an active database as if it were a consistent backup. If your storage system provides coordinated snapshots, follow its documented consistency procedure.

Restore on another machine

Restore into a separate directory, install the same server version, and configure the machine's model and compute prerequisites. Restore the original sealing key securely before starting, retaining restrictive permissions. Without it, saved model, tool, and MCP credentials cannot be decrypted; you must re-enter them in Settings.

Start one server against the restored directory.

For the published launcher used by the quickstart:

npx @parcha/agentrun@0.4 --data /path/to/restored-agentrun

Open the printed console address. Confirm the agents, revisions, and completed runs are present before starting new work. Configure a changed public URL or compute provider explicitly; restoring local data does not transfer an external provider's machines.

Do not run two servers against the same data directory. See Tool keys for the sealing-key storage contract.

Upgrading from an older layout

Current main uses a disk/ layout for agent/run data. It refuses older directories with runs under DIR/runs/; it does not silently migrate them. Still older releases stored one agent.sqlite per agent and also require a separate transition.

Keep the old installation and its data available under the old version. Start the new version with an empty data directory, then recreate the agent definitions you need using the console or API. Old history remains readable in the preserved installation.

Before upgrading, read The disk, and earlier data directories and the target release notes. A repository example from main is not an instruction to upgrade an existing store in place.

Move one agent's configuration

Read its definition and revisions through the API, then create an agent on the destination server. Check the destination's harnesses, tools, models, and compute first; copying a definition does not provision those dependencies.

There is no general promise that exporting a single home transfers complete run history and provider state. The current server marks packed home import/export as unsupported. Use a full server backup when you need to preserve the installation.