Transfer Factorio Space Age platforms between Clusterio instances. The project contains a TypeScript plugin, a save-patched Lua module and the gateway mod.
Install the plugin package into Clusterio and add the gateway mod to its mod pack. Use the installation guide to install the newest release explicitly. This repository's Docker setup is for development and acceptance tests. Use Clusterio or clusterio-docker to host the cluster.
Status: development / pre-production. Bounded transfer/recovery, coordinated volume restoration and packaged fresh-install fixtures pass. Upgrade compatibility, broader disaster recovery and supported operating limits remain open. The root Docker cluster is a development environment.
- Use gateways and transfer platforms
- Read outcomes and audit evidence
- Understand what happens when a server loads an older save
- Install and update the Clusterio plugin
- Create the production servers
- Configure the plugin
- Back up and recover worlds
- Set up development
- Build, test and contribute
- Understand Clusterio integration
The documentation index also covers queues, batching, validation, timing and recovery records for technical readers.
The plugin captures supported entity state, tiles, inventories, belt items, fluids and connections. It restores them in stages, validates destination cargo and coordinates source deletion and destination release. Standalone export/import and explicit snapshot recovery create copies and have different ownership behavior.
Gateways shows queued and active operations. Transaction Logs retains summaries, audit evidence and measured timings according to configured limits. Controller settings and per-instance batching/diagnostic settings have separate owners.
Lua runs synchronously inside each callback. Jobs share deterministic work limits and yield at selected boundaries; native codec calls and large individual work units can still stall simulation. Ticks and measured milliseconds are separate. See batching and timing.
Each page on the releases list, newest first, names the versions that release was built and tested with. The release workflow built and tested the exact package before publishing it to npm and attaching it there. The retained manual evidence below is older: the recorded package and consumer acceptance used 0.10.281, Clusterio 2.0.0-alpha.27 and Factorio Space Age 2.1.17. Those results identify historically tested artifacts, not a certification of every later source revision or a statement about the currently published release. The current seed runtime and dependency pins are in their configuration; the Docker image revision is in .env.example.
| Area | Retained evidence and limits |
|---|---|
| Transfer recovery | Manual fixtures cover their save-policy, lost-reply and crash boundaries with independent cargo checks. Original failures remain recorded. |
| Destination save rollback | The original rollback case left a missing platform. Explicit snapshot restoration is a separate import, not automatic repair of that old outcome. |
| Backup/restore | Docker acceptance fixture restored all twelve resolved stores into fresh resources on the same machine/image pair, then checked cargo, history, settings, authentication, assets and another transfer. Mixed generations and off-host disaster recovery remain separate cases. |
| Installation | Package acceptance and consumer installation record exact bytes, fresh worlds and native checks. Fresh installation is not proof of historical upgrade or code-rollback compatibility. |
| Performance | Retained experiments identify fixture sizes and measured boundaries. There is no general no-lag, platform-size or transfer-duration guarantee. |
Do not treat an unavailable status as permission to replay an import or unlock a protected source. Follow recovery and preserve both worlds and their matching journals before intervention.
| Path | Purpose |
|---|---|
| Plugin | Controller, instance bridge, CLI, web UI and Lua module |
| Gateway mod | Factorio prototypes and graphics |
| Tools | Build, deployment, diagnostics and test helpers |
| Tests | Regressions, fixtures and retained experiments |
| Documentation | Human guides by task and audience |
Use Issues for actionable bugs, Discussions for questions, and private reporting for security concerns. See contributing.
MIT.