Import And Export Agents
Move agents between local, PC, and VPS engines with .xcloud-agent packages.
xCloud can export an agent into a .xcloud-agent package and import it into another engine.
Use this when you want to move an agent from your laptop to a VPS, share a public agent, back up an agent, or clone an agent into another setup.
What A Package Includes
A .xcloud-agent package can include:
| Item | Included |
|---|---|
| Agent identity files | Yes |
| Instructions and project brief | Yes |
| Memory files listed as safe | Yes |
| Avatar and image assets | Yes |
| Notes folder | Yes |
| Agent UI project | Yes, when one exists |
.env files | No |
node_modules | No |
| build output | No |
.git history | No |
Excluded folders keep packages smaller and avoid leaking secrets.
Export An Agent
- Open the agent menu in the sidebar.
- Choose Export.
- Save the
.xcloud-agentfile.
xCloud creates a package with a manifest, agent files, and the UI folder if the agent has one.
Import An Agent
- Open the sidebar import action.
- Choose the
.xcloud-agentpackage. - Wait for the import progress to finish.
- The imported agent appears in the sidebar.
If an agent with the same id already exists, xCloud creates a unique id by adding a suffix.
Importing Into A Remote Engine
For a VPS or PC engine, xCloud does more work:
- Unpacks the package locally.
- Re-packs it into a tar archive.
- Uploads the archive to the remote engine in chunks.
- Extracts it into
~/.openclaw/workspace/<agent-id>. - Registers the agent in the remote OpenClaw config.
- Writes
ui-config.jsonif the package includes an Agent UI.
Large packages can take time. The import progress appears in the sidebar so the app can still be used.
Expected Import Time
| Package | Local engine | Remote engine |
|---|---|---|
| Small agent, no UI | Seconds | Seconds |
| Agent with React UI | Seconds | 1-3 minutes |
| Large UI/assets | Longer | Longer, depends on network |
If it looks stuck, check whether the progress text is still changing. Uploading many chunks can be slow on a VPS connection.
Common Errors
| Error | Meaning | Fix |
|---|---|---|
Argument list too long | A package was passed through a shell command incorrectly | Use the current importer, which uploads package chunks instead of one huge argument |
Package is missing agent files | The archive does not contain the expected agent/ folder | Re-export the agent |
not a valid xCloud agent package | Missing or invalid manifest | Choose a .xcloud-agent exported by xCloud |
| Import finishes but agent is missing | Config reload failed or active engine changed | Refresh agents and confirm the active engine |
| Agent appears but UI is missing | Package did not include UI or ui-config.json was not written | Open the agent UI page and reconnect the UI folder |
Security Notes
Before sharing a package publicly:
- Remove private memory.
- Remove customer data from notes.
- Confirm no
.envor secret files are inside the UI folder. - Test importing into a clean engine.