agentx export and import

Export writes a snapshot of this machine to a file in your library, or to your account remote: your settings, your agent configurations, the skills in your library with where each one is placed, and the MCP servers and plugins agentx found. Import applies a snapshot: it restores the settings, installs the skills, and places each one where the snapshot says. A snapshot is the whole state of one machine, so it always holds that machine’s settings. A snapshot holds no skill content. For each skill it records where the skill comes from, which version you had and which configurations you placed it in. Import installs the content again from each skill’s source, or from your account remote for your own skills.

Move to a new machine

On the old machine, run agentx export. It writes snapshot.json to your library, ~/.agents/skills by default.
Copy the file to the new machine, for example to ~/snapshot.json.
On the new machine, run agentx import ~/snapshot.json, and answer y.

Import installs each skill at the version you had and places it in the same configurations. Use the same steps to restore a machine from its own snapshot, for example after you removed your skills.

Export this machine

agentx export

✓ exported the settings and 12 skills to /home/me/.agents/skills/snapshot.json

Export writes the file to your library, next to your skills, where every agent that reads the library leaves it alone. Without a name, the file is snapshot.json. Give a name to keep more than one snapshot:

agentx export work-laptop

✓ exported the settings and 12 skills to /home/me/.agents/skills/work-laptop.json

The name is a file name without an extension. Export adds .json. A name with an extension, a slash, or a leading dot stops export with exit code 1. agentx export --help prints the path of the file export writes. The file holds:

Part	What it is
`settings`	Your settings as `settings.json` holds them, for example the label, your sources and their pins, disabled configurations and copy modes.
`configurations`	Each agent configuration on this machine, by its id, such as `claude-code`, and whether it is enabled.
`skills`	One entry for each skill in your library: its name, whether agentx manages it, where it is published (its source, or your account remote for your own skills), where a skill you forked came from (its upstream), the version it is at, and the configurations it is placed in.
`mcp_servers`	Each MCP server, with the tools it exposed, the configurations that declare it, and the command, arguments or URL each one declares, as written there. Only the names of environment variables and headers are kept, never their values.
`plugins`	Each plugin, with its marketplace, version and configuration.
`machine`	The id and label of the machine you exported from.

A snapshot leaves out what only describes this machine: where agentx found each configuration, skill and plugin on disk, whether a skill is modified or has drifted, and the ids agentx scan uses. Two exports of an unchanged machine are the same file, byte for byte, so you can compare them. A snapshot keeps each MCP server’s command, arguments and URL as your configuration writes them, and these can hold a token. Treat the file like a secret, and do not commit it to a public repository. A new file is readable by you alone. When you overwrite a file with --force, it keeps its old permissions. If the file is already there, export stops with exit code 6. Pass --force to replace it:

agentx export --force

If a directory of that name is in the library, export stops with exit code 6, also with --force. If you have no library yet, export creates it. If a skill in your library has a name agentx cannot store as a branch, export leaves it out of the snapshot and prints a warning that names it. If agentx cannot read your library, or part of it, export prints a warning for each problem, as agentx skill list does, and the snapshot leaves out what it could not read. Fix the problem the warning names and export again.

Import onto another machine

Import takes the path of a snapshot file:

agentx import ~/snapshot.json

Replace the settings in /home/me/.agentx/settings.json with those of my-laptop from /home/me/snapshot.json, and install, update and place its 4 skills? [y/N] y
✓ imported the settings of my-laptop from /home/me/snapshot.json
  added source https://github.com/example/skills: 12 skills
  added source https://github.com/example/tools pinned to v2: 3 skills
4 skills in the snapshot: 1 installed, 1 updated, 1 kept, 1 skipped
  pdf     managed    installed  https://github.com/example/skills/skills/pdf       placed in claude-code, codex
  xlsx    managed    updated    https://github.com/example/skills/skills/xlsx      placed in claude-code
  review  managed    kept       ssh://git@github.com/you/agentx-account (account)  not placed
  notes   unmanaged  skipped    (none)                                             not placed
  skipped notes: notes is unmanaged, so there is no source to install it from

Import asks once. Answer y or yes to apply the whole snapshot. Any other answer changes nothing, so answering no is how you check a snapshot first. Import then does this:

The snapshot has	What import does
Settings	Replaces your settings with them, but keeps this machine’s URL of your account remote, see below. agentx checks write access to each source again on this machine.
Sources in the settings	Adds each source this machine has not added yet, your account remote included, at the pin the settings hold. Import prints one line per source it adds.
A skill this machine lacks	Installs it. A skill of a source comes from that source, and one of your own from your account remote.
A skill at a newer version	Updates it to that version.
A skill this machine has	Places it in the configurations the snapshot names, and takes it out of the others. Only the configurations agentx detects on this machine count.
A skill it cannot install	Skips it, and prints why.
MCP servers and plugins	Nothing, for now.

Import never deletes a skill. A skill in your library that the snapshot does not list stays as it is. If you deleted a skill’s folder from your library by hand, import skips that skill and prints the command that brings it back. Import only moves a skill forward:

A skill that is newer on this machine than in the snapshot stays at its version.
A skill you edited and did not publish stays as it is. Import skips it and tells you to run agentx skill update <name>, which merges your edits with the newer version.
A skill whose history went another way on this machine is skipped too. Run agentx skill update <name> to merge it.

Codex and Gemini CLI read your library, so they see every skill in it, whatever the snapshot says. To install your own skills, import needs your account remote. The snapshot’s settings bring it along. One repository can have more than one URL. Your laptop may reach your account remote over SSH, as git@github.com:you/agentx-account.git, while a cloud agent reaches it over HTTPS, as https://github.com/you/agentx-account, with a token that can only read. Import treats both as your account remote, because they have the same host and path. When the snapshot’s account remote is the same repository as this machine’s, import keeps this machine’s URL, so each machine goes on reaching it its own way. When the snapshot names another repository, import switches this machine to that one. A host alias from your SSH configuration, such as github-work, does not count as the host it stands for here, because import reads no SSH configuration. Each line of the listing says what import did with that skill:

Action	Meaning
`installed`	This machine did not have the skill. Import installed it and placed it.
`updated`	Import moved the skill to the version the snapshot names, or to the latest version.
`placed`	The skill was at its version. Import placed it in a configuration it was missing from.
`unplaced`	The skill was at its version. Import only took it out of configurations.
`kept`	Nothing changed: the skill is at its version, or newer, and placed as the snapshot says.
`skipped`	Import left the skill as it is. The line under the listing says why.

The last column names the configurations the skill is placed in now. Run the same import again and it changes nothing: every skill reads kept, or skipped for the same reason as before. Import fetches nothing for a skill the snapshot names at an exact version. It fetches a skill that follows the latest version again, and moves it forward when a newer version exists. It installs a skill it skipped once the reason is gone. Import adds every source of the settings, whether a skill of the snapshot comes from it or not, so you can install from any of them right away. It keeps each source’s pin. A source that this machine has already added and fetched is not fetched again, so a second import of the same snapshot does not reach the network for it. If import cannot reach a source, it prints a warning with git’s reason and goes on: the other sources and the skills are still applied, and import still succeeds. It ends with an agentx source add line for each such source:

warning: could not add a source of the imported settings: https://github.com/example/private: git fetch: fatal: could not read Username for 'https://github.com': terminal prompts disabled
...
  add these sources again before you install from them:
    agentx source add https://github.com/example/private#main

Fix the cause, such as a missing credential, then run the line as printed, or run the import again. The line keeps the source’s pin, and import quotes a URL or pin where needed, so you can paste it into bash or zsh. If import stops part way, for example because the machine shut down, the next agentx command finishes the change import was making. Run the import again to apply the rest, the sources it did not add included.

Keep a snapshot on your account remote

Instead of a file, export can write the snapshot to your account remote, on the branch machines/<machine id>, and import can read it from there. The branch holds one file, snapshot.json, the same file an export to a file writes. agentx writes to the account remote only when you name a machine with --machine, and never on its own. The snapshot on the branch keeps each MCP server’s command, arguments and URL, as a snapshot file does, and these can hold a token. Anyone who can read your account remote can read them, a cloud agent’s read-only token included. Keep the account remote private, and give read access only to people and agents you trust with those values.

Back up this machine

Export to this machine’s id. agentx export --help prints it, and so does agentx machine:

agentx export --machine 0123456789abcdef0123456789abcdef

✓ exported the settings and 12 skills to machines/0123456789abcdef0123456789abcdef on the account remote at 4c2e9a1

Each export writes one commit and pushes it. agentx never forces the push. If the snapshot is unchanged since the last export, agentx pushes nothing and says so.

Seed another machine

Export to another machine’s branch to give that machine this machine’s skills. To give your cloud agents the skills of this machine, export to the cloud machine:

agentx export --machine cloud

To change one skill on the cloud machine later, see Turn skills on for your cloud agents.

Restore from the account remote

On the machine to restore, add your account remote, then import the branch:

agentx source add <url> --account
agentx import --machine 0123456789abcdef0123456789abcdef

Import reads the snapshot from that one branch and pushes nothing, so a token that can only read your account remote is enough. It then applies the snapshot as it applies a file: it asks once, restores the settings, installs each skill and places it where the snapshot says. Without a terminal, pass --yes, see Confirm without a terminal. To set up a new computer from another machine, import that machine’s branch once. After that, the two machines are independent. If the account remote has no branch for that machine, import stops with exit code 5. If another machine or the web app changed the branch since agentx read it, an export stops with exit code 6 and pushes nothing: run it again.

Confirm without a terminal

Import changes your settings and your skills, so it asks first. Pass --yes to answer in advance:

agentx import ~/snapshot.json --yes

Use --yes in scripts, with --json, and wherever there is no terminal. Without --yes, import exits with code 6 and changes nothing in these cases. It does the same when you answer anything other than y or yes.

When an import is refused

Exit code	Cause
3	The account remote cannot be reached.
5	The file is not there, or the account remote has no branch for the machine you named.
6	The file is not a valid agentx snapshot: it is damaged, larger than 8 MiB, from an agentx version this one cannot read, holds no settings, or holds a setting or skill entry agentx would not write. The message names the problem. Export the file again from the other machine, or upgrade agentx.
6	The file is an export from an earlier version of agentx. Import no longer reads that format. Export the file again on the other machine with this version of agentx.
6	With `--machine`: no account remote is set, or the machine’s branch holds no `snapshot.json`. Add the account remote with `agentx source add <url> --account`.
6	You answered no, or import could not ask (no terminal, or `--json`) and you did not pass `--yes`.

A refused import changes nothing: your settings and your skills stay exactly as they were. A skill import skips does not make it fail: the import goes on with the others and exits with code 0.

Get started

Inventory

Skills

This machine

Reference