{"id":13595826,"url":"https://github.com/clusterio/clusterio","last_synced_at":"2026-01-12T02:16:44.841Z","repository":{"id":37000955,"uuid":"65576660","full_name":"clusterio/clusterio","owner":"clusterio","description":"internet communication for factorio mods","archived":false,"fork":false,"pushed_at":"2025-03-23T17:25:38.000Z","size":15725,"stargazers_count":349,"open_issues_count":58,"forks_count":73,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-02T03:47:06.010Z","etag":null,"topics":["factorio","game","mod"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clusterio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-12T18:54:04.000Z","updated_at":"2025-03-25T05:15:55.000Z","dependencies_parsed_at":"2023-07-16T23:06:23.472Z","dependency_job_id":"38151945-a775-42ad-9c50-088fd9892f9c","html_url":"https://github.com/clusterio/clusterio","commit_stats":{"total_commits":2193,"total_committers":51,"mean_commits":43.0,"dds":0.4870041039671683,"last_synced_commit":"4d66dc5de3a69abbddef8434365cfda7dfae397b"},"previous_names":["clusterio/factorioclusterio"],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clusterio%2Fclusterio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clusterio%2Fclusterio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clusterio%2Fclusterio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clusterio%2Fclusterio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clusterio","download_url":"https://codeload.github.com/clusterio/clusterio/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247615412,"owners_count":20967183,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["factorio","game","mod"],"created_at":"2024-08-01T16:01:58.634Z","updated_at":"2026-01-12T02:16:44.797Z","avatar_url":"https://github.com/clusterio.png","language":"TypeScript","funding_links":["https://www.patreon.com/danielv123"],"categories":["TypeScript","game"],"sub_categories":[],"readme":"\u003cimg src=\"./logo.svg\" width=\"100%\" align=\"right\"\u003e\n\n\u003cbr/\u003e\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n# Clusterio\n\nDiscord for development/support/play: https://discord.gg/5XuDkje\n\n## Important notice\n\nClusterio 2.0 is still in alpha, however the previous stable has been abandoned and is no longer supported.\nDespite being alpha it's reasonably stable now and there's no major breakages expected before a stable release of 2.0.\nIf you are starting a new cluster, it's highly recommended to use the 2.0 alpha.\n\n\n### Ways to support me/the project:\n\n* Contribute with code/documentation.\n  See [Contributing](docs/contributing.md) for how to make pull requests.\n  Always nice to move the project forward.\n\n* Support me monetarily on [patreon](https://www.patreon.com/danielv123) or paypal: danielv@live.no\n\n### Table of contents\n\n* [Introduction](#introduction)\n* [Features](#features)\n* [Plugins](#plugins)\n* [Installation](#installation)\n  * [Ubuntu setup](#ubuntu-setup)\n  * [Windows setup](#windows-setup)\n  * [MacOS setup](#macos-setup)\n  * [Installing Plugins](#installing-plugins)\n* [Configure Controller](#configure-controller)\n* [Managing Factorio mods](#managing-factorio-mods)\n* [Setting up shared storage](#setting-up-shared-storage)\n* [Running Clusterio](#running-clusterio)\n* [Setting up remote hosts](#setting-up-remote-hosts)\n* [Setting up clusterioctl](#setting-up-clusterioctl)\n* [Known issues](#known-issues)\n* [Common problems](#Common-problems)\n\n\n## Introduction\n\nClusterio is a clustered Factorio server manager that provides the tooling for implementing cross server interactions in Factorio.\nIt was previously best known for implementing cross server transfer and cloud storage of items via teleporter chests.\nBut this functionality has been pulled out of Clusterio into its own plugin for Clusterio named [Subspace Storage](https://github.com/clusterio/subspace_storage).\n\nBy itself Clusterio doesn't change the gameplay in any way, you could even use Clusterio to manage completely vanilla Factorio servers.\nPlugins do the work of modding in the visible changes into the game, see the [Plugins section](#plugins) for ready-made plugins you can install into a Clusterio cluster.\n\n\n## Features\n\n- Clustered Factorio server management allowing you manage the running of Factorio servers across a fleet of physical servers from both a web interface and a command line interface.\n\n- User list management for synchronizing in-game admins, whitelisted users, and bans to all the servers in the cluster.\n\n- Integrated support for exporting statistics for the whole cluster to Prometheus via a single metrics endpoint.\n\n- Extensive plugin support for adding your own cross server features to Factorio using Clusterio's communication backbone.\n\n\n## Plugins\n\nThe heart of Clusterio is its plugin system.\nPlugins add functionality to Factorio servers, Clusterio itself or both.\nThese are the plugins supported and maintained by the Clusterio developers:\n\n- [Global Chat](/plugins/global_chat/README.md): share the in-game chat between servers.\n- [Research Sync](/plugins/research_sync/README.md): synchronize research progress and technologies unlocked between servers.\n- [Statistics Exporter](/plugins/statistics_exporter/README.md): collect in-game statistics from all the servers and makes it available to the Prometheus endpoint on the controller.\n- [Subspace Storage](https://github.com/clusterio/subspace_storage): Provide shared storage that can transport items between servers via teleport chests.\n- [Player Auth](/plugins/player_auth/README.md): Provides authentication to the cluster via logging into a Factorio server.\n- [Inventory Sync](/plugins/inventory_sync/README.md): Synchronizes your inventory between servers.\n\nThere's also plugins developed and maintained by the community:\n\n- [Discord Bridge](https://github.com/Hornwitser/discord_bridge) (@hornwitser/discord_bridge): Bridges chat between instances and Discord.\n  By Hornwitser.\n- [Server Select](https://github.com/Hornwitser/server_select/tree/clusterio-2.0) (@hornwitser/server_select): In-game GUI for connecting to other servers in the cluster.\n  Originally by Godmave, ported to 2.0 by Hornwitser.\n\nWant to make your own plugin?\nCheck out the documentation on [Writing Plugins](/docs/writing-plugins.md) for where to start.\n\n\n## Installation\n\nClusterio runs on all LTS version of NodeJS, it is distributed via npm and comes with a guided install script.\nIf you already have a recent Node.js installed, you can set it up in a new directory with:\n\n    npm init \"@clusterio\"\n\nOtherwise see below for OS specific instructions.  \nCheck out all our of decisions for [node, factorio, and operation support](/docs/decisions.md#supportability).\n\n### Ubuntu setup\n\n1.  Install Node.js v18 or higher.\n    Note the version of Node.js provided by the Ubuntu/debian repos are too old and you will have to use the nodesource PPA\n\n        curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - \u0026\u0026\\\n        sudo apt-get install -y nodejs\n\n2.  Log in as the user you wish to install Clusterio as (do not use root), and then create a new directory and run the Clusterio installer:\n\n        mkdir clusterio\n        cd clusterio\n        npm init \"@clusterio\"\n\n    Make sure to note down the admin authentication token it provides at the end as you will need it later.\n\n3.  Optionally copy the generated systemd service files in `systemd` folder to `/etc/systemd/system/`.\n\n\n**Ubuntu with Docker**\n\nThe Docker support for Clusterio is currently broken.\nIf you need it open an issue about it.\n\n\u003c!--\nClusterio has *very* limited support for using docker.\n\n    sudo docker build -t clusterio --no-cache --force-rm clusterio\n\n\tsudo docker run --name controller -e MODE=controller -p 1234:8080 -d -it --restart=unless-stopped danielvestol/clusterio\n\n\tsudo docker run --name host -e MODE=host -e INSTANCE=world1 -v /srv/clusterio/instances:/clusterio/instances -p 1235:34167 -it --restart=unless-stopped danielvestol/clusterio\n\nThe -v flag is used to specify the instance directory.\nYour instances (save files etc) will be stored there.\n--\u003e\n\n### Windows setup\n\n1.  Download and install the latest LTS release from http://nodejs.org.\n\n2.  Create a new empty directory for the installation and navigate into it.\n    Open a PowerShell window in this new directory by Shift+Right clicking inside it and choosing \"Open PowerShell window here\" and then run the following command.\n\n        npm init \"@clusterio\"\n\n    Make sure to note down the admin authentication token it provides at the end as you will need it later.\n\n3.  If you chose to use local factorio directory for the Factorio installation, download the Windows 64-bit zip package from https://www.factorio.com/download and extract it to the `factorio` folder in your clusterio installation folder.\n\n\n### MacOS Setup\n\n1.  Install the latest Node.js LTS release from http://nodejs.org or use brew (`brew install node`).\n\n2.  Open Terminal or Command prompt in the directory you want to install to and run the following commands.\n\n        mkdir clusterio\n        cd clusterio\n        npm init \"@clusterio\"\n\n    Make sure to note down the admin authentication token it provides at the end as you will need it later.\n\n3.  If you chose to use local factorio directory for the Factorio installation, you will need to obtain and copy a mac version of Factorio and unpack it to the `factorio` folder in your clusterio installation folder.\n\n\n### Installing Plugins\n\nFor well-known plugins you can select them during installation and no further steps are necessary to make them work.\nInstalling plugins that are not offered by the installer consists of two steps.\nFirst install the package the plugin is provided by via npm, for example\n\n    npm install @clusterio/plugin-subspace_storage\n\nThen tell clusterio that this plugin exists by adding it as a plugin.\n\n    npx clusteriocontroller plugin add @clusterio/plugin-subspace_storage\n\nThis adds it to the default `plugin-list.json` file which in the shared folder setup is loaded by controller, host and ctl.\nIf you have hosts or ctl installed on separate computers (or directories) then you need to repeat the plugin install process for all of them.\nThe clusteriocontroller, clusteriohost and clusterioctl commands has the plugin sub-command so you do not need to install clusteriocontroller to add plugins, instead use the clusterio command you have available.\n\nFor development purposes the `plugin add` command supports adding plugins by the absolute path to them, or a relative path that must start with either . or .. (which will then be resolved to an absolute path).\n\n\n## Configure Controller\n\nBy default the controller will listen for HTTP on port 8080.\nYou can change the port used with the command\n\n    npx clusteriocontroller config set controller.http_port 1234\n\nWhen changing the port you will also need to change the address hosts connect with.\nFor the standalone installation mode you can use\n\n    npx clusteriohost config set host.controller_url http://localhost:1234/\n\nIf you plan to make your cluster available externally set the address\nthat it will be accessible under with, for example\n\n    npx clusteriocontroller config set controller.public_url http://203.0.113.4:1234/\n\nChange the url to reflect the IP, protocol, and port the controller is accessible under, dns names are also supported.\nIf you're planning on making the controller accessible on the internet it's recommended to set up TLS, see the [Setting Up TLS](/docs/setting-up-tls.md) document for more details.\n\nYou can list the config of the controller with the `npx clusteriocontroller config list` command.\nSee the [readme for @clusterio/controller](/packages/controller/README.md) for more information.\n\n\n## Managing Factorio mods\n\nMods in clusterio are managed as parts of modpacks. There is currently no mod portal integration, so you first need to navigate to the mods section of the web UI and upload your mods. You can then create a modpack from the uploaded mods by navigating to the mods page, hitting `create`. Once you have a modpack, you can assign it to an instance under Instance config -\u003e Factorio -\u003e Mod pack. You can also set a default modpack for new instances in the controller settings.\n\n![Select mod pack for instance](docs/assets/config_select_mod_pack.png)\n\nMod settings can be managed under the modpack configuration page in the web UI. For mod settings to show, you first need to run an export. This is done by creating an instance with the modpack assigned, opening the instance page and pressing More -\u003e Export data.\n\n![Export mod configuration data](docs/assets/export_mod_config_data.png)\n\nOnce this is done, the mod settings will show up under the modpack configuration page.\n\n![Mod settings configuration in web interface](docs/assets/mod_settings_configuration.png)\n\n\n## Setting up shared storage\n\nThe chests teleporting items to and from the shared storage on the controller has been moved into the Subspace Storage mod and plugin.\nTo get this to work you will need to install the Subspace Storage plugin and copy the [Subspace Storage mod](https://mods.factorio.com/mod/subspace_storage) and the [Clusterio Lib mod](https://mods.factorio.com/mod/clusterio_lib) into the `sharedMods` folder on each host installation.\n\nDo not install the [Clusterio mod](https://mods.factorio.com/mod/clusterio), this was for the old 1.2.x version of Clusterio and is not compatible with Clusterio 2.0.\n\n\n## Running Clusterio\n\nAfter completing the installation start up the controller and at least one host separately.\nThe installer provides the `run-controller` and `run-host` scripts to make this simple.\nOnce the controller process is running you can log into the web interface which is hosted by default on http://localhost:8080/ (adjust the port number if you changed it), use the admin authentication token provided from the installation to log in.\n\nThe basics of setting up a Factorio server from the web interface is to create an instance, assign it to a host and then click start. You can also use the \"Connect via Steam\" button to launch Factorio directly and connect to the server using Steam's protocol handler.\n\n### Running via Systemd\n\nThe install script creates systemd service scripts for clusteriocontroller and clusteriohost (if applicable) to start up as the user than ran the installer.\nIf you have copied these files over to `/etc/systemd/system/` then you can startup Clusterio as a background service using:\n    \n#### To start as a service run:\n \n    sudo systemctl start clusteriocontroller # for the controller\n    sudo systemctl start clusteriohost # for each physical server intended to host Factorio servers\n\n#### To automatically get it to start on boot:\n \n    sudo systemctl enable clusteriocontroller # for the controller\n    sudo systemctl enable clusteriohost # for each physical server intended to host Factorio servers\n\n\n## Setting up remote hosts\n\nRun the installer as described in the installation section and choose \"Host only\" as the operating mode to install, it'll ask for a controller URL and an authentication token.\nThe URL is the same as what is needed to connect to the web interface, and the authentication token can be generated on the Hosts page in the web interface.\nOnce you start up the host it should show up in the Hosts list and be available for assigning and running instances on.\n\n\n## Setting up clusterioctl\n\nThere's a command line interface available for Clusterio which is installed separately with the same installer as for the controller and host.\nRun the installer as described in the installation section and choose \"Ctl only\" as the operating mode to install, you can do this in the same directory as you have installed other Clusterio component(s) to.\nThe installer will ask for a controller URL and an authentication token, these are the same as you would use to connect to the web interface.\nIf you want to use a different user for the command line interface, you can generate an authentication token for an existing user with\n\n    npx clusteriocontroller bootstrap generate-user-token \u003cusername\u003e\n\n\n## Known Issues\n\n- When the `server_select` plugin is installed you may see `[error] Unhandled event server_select:UpdateInstancesEvent` logged when starting an instance.\n  This should be ignored as it does not indicate an error occured.\n- After updating Factorio you may get the error `Error: Expected empty response but got \"Cannot execute command. Error: [string \"clusterio_private.update_instance(...\"]:1: attempt to index global 'clusterio_private' (a nil value)?` on instance start.\n  This is due to Factorio applying a migration replacing the patched content of the save with the original scenario, attempting to start the instance again should resolve the issue.\n- In the mod pack view of the web interface the \"base\" mod is displayed with an error complaining about the mod being missing from the controller storage.\n  This is due to the \"base\" mod currently not being connectly handled as a built-in mod to Factorio in the web interface, this error message should be ignored.\n- After migrating from Alpha 13 to Alpha 14 running an instance data export fails with the error `Upload failed: 401 Unauthorized` due to the host token being issued to a slave.\n  To workaround this find the id of the host in the host config and generate a new host token with the same id.\n  Stop the host and replace the value of the `host.controller_token` field in `config-host.json` with the new host token before starting it up again.\n- After migrating from Alpha 13 to Alpha 14 you get kicked out from the web interface due to the master to controller rename.\n  If you don't have the authentication token readily available you can manually migrate the token by opening the Inspect/Developer Tools on the page and running the following piece of JavaScript in the Console:\n  ```\n  localStorage.controller_token = localStorage.master_token\n  ```\n\n\n## Common problems\n\n### EACCESS [...] LISTEN 443\n\nSome systems don't let non root processes listen to ports below 1000.\nEither run with `sudo` or change config.json to use higher port numbers.\n\nAccording to [this link](https://askubuntu.com/questions/839520/open-port-443-for-a-node-web-app) if you manually installed node.js following the above instructions, you may need to run the following command to fix this issue:\n\n    sudo setcap 'cap_net_bind_service=+ep' $(readlink -f $(which node))\n\n### Port forwarding doesn't work on the controller when running under WSL\n\nIf you follow the ubuntu guide on WSL (Windows Subsystem for Linux, Bash on Ubuntu on Windows specifically), you will find that the website works on localhost and on your local ip, but not on the global ip.\nThis is also true when you correctly port-forwarded the correct ports.\nEven when routing this server through nginx in WSL, the issue persists.\nThen, on a hunch, I tried to run nginx from windows itself and found that this DID work.\nIt came to me that the only usage difference between the 2 versions of nginx is that I got a Windows Firewall popup.\n\nTLDR: the tested fix is:\n\n- open your windows firewall and go to advanced settings\n\n- click on inbound rules and click on new rule...\n\n- select port and click next \u003e\n\n- select TCP and select specific local ports and type in the ports that you want to open (comma separated) and click next \u003e 3 times\n\n- give the rule a name (like 'web server' or something), give it a description (optionally) and click finish\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclusterio%2Fclusterio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclusterio%2Fclusterio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclusterio%2Fclusterio/lists"}