Files
factorio-clusterio/docs/clusterioctl.md
T
bbassieandClaude Opus 5.5 fb93962972 Document clusterioctl setup and the missing commands
Adds a setup section covering the installer, create-ctl-config, a
hand-made config and self-signed certificates. Documents the commands
that were missing or marked "To be written": controller and host
stop, restart and config, instance start, restart, stop, start-all,
stop-all, load-scenario, delete, send-rcon and export-data, saves,
config set-prop, mods, mod packs, user show and revoke-token, roles,
permissions and logs.

Part of #1254

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-22 00:00:06 +00:00

36 KiB

Clusterioctl

Clusterio clusters can be managed from the command line with clusterioctl, which is invoked by running npx clusterioctl <command> in the clusterio directory. It connects to the controller the same way the web interface does, and what it is allowed to do depends on the roles of the user it logs in as. See Managing a Cluster for a guide to the day to day tasks. This document uses the shorthand ctl> foo to indicate npx clusterioctl foo should be executed. Mandatory parameters are shown in <angles bracket> and optional pameters are in [square brackets]. Hosts, instances, roles and mod packs can be given by name or by ID.

Run npx clusterioctl --help for the list of commands and npx clusterioctl <command> --help for the options of a command. Plugins may add their own commands, these are documented in the plugin's README.

Setting up

clusterioctl is installed separately from the controller and host. Run the installer as described in the README and choose "Ctl only" as the operating mode, either in the same directory as the controller or on another computer. The installer asks for the controller URL and an authentication token, these are the same as you would use to log in to the web interface, and saves them to config-ctl.json.

When clusterioctl is installed in the same directory as the controller, npx clusteriocontroller bootstrap create-ctl-config <username> writes config-ctl.json for managing the cluster as the given user. The config created this way connects to localhost, so it only works on the controller computer.

To set it up by hand, generate a token for the user on the controller:

npx clusteriocontroller bootstrap generate-user-token <username>

Then create the config and set the URL and token on the computer you run clusterioctl on:

npx clusterioctl config create
npx clusterioctl config set ctl.controller_url https://example.com/
npx clusterioctl config set ctl.controller_token <token>

The config command works offline and is described in the readme for @clusterio/ctl, along with the other command line options. See Ctl Configuration for the available settings.

The token logs in as the user it was generated for and gives the same access as that user's roles. Anyone holding it can manage the cluster as that user, so keep config-ctl.json private. A token stops working when it is revoked with user revoke-token.

If the controller uses a self-signed certificate, Node.js has to be told to trust it before clusterioctl can connect, see Setting up TLS. For example on Linux:

NODE_EXTRA_CA_CERTS=path/to/cert.pem npx clusterioctl instance list

Output Format

ctl> --output json <command>

Print the result of the command as JSON on stdout instead of text meant for reading. Lists are printed as an array of objects, other results as an object, and commands that have no result print {"success": true}. If the command fails it prints {"error": "<ClassName>", "message": "<message>"} and exits with a non-zero exit code. Log messages are written to stderr in all formats.

--output wire prints the same results in the format they are sent between the controller, hosts and clusterioctl, which uses snake_case names like is_admin. The json format uses the property names shown in the tables of the human format.

log follow and debug dump-ws keep running and print one JSON object per line as entries arrive. instance start-all and instance stop-all print an array with an entry per instance, which has an error property if that instance failed to start or stop.

The default is --output human, which prints Command ran successfully for commands that have no result.

Controller

Stop controller

ctl> controller stop

Stops the controller. The run scripts and systemd services created by the installer do not start it again.

Restart controller

ctl> controller restart

Restarts the controller. This only works if the controller was started with run --can-restart, which the run scripts and systemd services created by the installer do, otherwise the request is refused. It is also refused while a plugin install or update is running.

Controller config

The controller config can be changed while the controller runs, unlike npx clusteriocontroller config set which must only be used while it is stopped. See Controller Configuration for the available fields.

List controller config

ctl> controller config list

Lists the config of the controller.

Set controller config value

ctl> controller config set <field> [value] [--stdin]

Sets a field in the controller config. If value is left out the field is cleared, --stdin reads the value from stdin instead. Some fields, like controller.allow_remote_updates, can not be changed remotely and have to be set on the controller computer while it is stopped.

Set controller config property

ctl> controller config set-prop <field> <prop> [value] [--stdin]

Sets one property of an object field in the controller config, see Set config property of field.

Edit controller config

ctl> controller config edit [editor]

Opens the controller config in a text editor and applies the changed values once the editor exits. If editor is not given the EDITOR or VISUAL environment variable is used.

Hosts

List hosts

ctl> host list

Lists all hosts.

Hosts are added to the cluster by running the installer on the computer the host runs on and approving the code it shows, see Setting up remote hosts. Listing, approving and rejecting hosts waiting for approval needs the core.host.approve permission.

List pending hosts

ctl> host pending

Lists hosts waiting for approval with the code they show, the name they asked for, the address they connected from and how long they have been waiting. A request goes away when its host stops waiting, and after the time set by controller.host_pairing_timeout, an hour by default, after which the host asks again with a new code.

Approve host

ctl> host approve <code> [--name <host name>]

Approves the host showing the code and prints the id of the new host. The code is not case sensitive and the dash can be left out. --name gives the host a different name than the one it asked for. Approving gives the host full access to the cluster, check with host pending that the name and address match the computer you are setting up.

Reject host

ctl> host reject <code>

Rejects the host showing the code, the host then exits with an error.

Revoke host

ctl> host revoke <host>

Specify the host by name or ID. Removes the host from the cluster, disconnects it and makes its token stop working. Instances assigned to the host become unassigned, their files stay on the computer. Requires the core.host.revoke permission. To add the computer back to the cluster, start the host again and approve it.

Stop host

ctl> host stop <host>

Stops the host and the instances running on it. The run scripts and systemd services created by the installer do not start it again, it has to be started on the computer it runs on.

Restart host

ctl> host restart <host>

Restarts the host. Like the controller, this only works if the host was started with run --can-restart.

Host config

The config of a connected host can be changed from clusterioctl. See Host Configuration for the available fields.

List host config

ctl> host config list <host>

Lists the config of the host given by name or ID.

Set host config value

ctl> host config set <host> <field> [value] [--stdin]

Sets a field in the host config. If value is left out the field is cleared, --stdin reads the value from stdin instead. Some fields, like host.allow_remote_updates, can not be changed remotely and have to be set on the host computer while it is stopped.

Set host config property

ctl> host config set-prop <host> <field> <prop> [value] [--stdin]

Sets one property of an object field in the host config, see Set config property of field.

Edit host config

ctl> host config edit <host> [editor]

Opens the host config in a text editor and applies the changed values once the editor exits. If editor is not given the EDITOR or VISUAL environment variable is used.

Update Clusterio

ctl> host update <host> [--all] [--restart]

Specify the host by name or ID. If remote updates are enabled on the host, this will attempt to update @clusterio/host on the machine. Add --all to also update all npm-installed plugins. Changes will not be applied until the host is restarted. If the --restart flag is provided, the host will automatically restart once the update is complete.

Remote updates are enabled by default but can be disabled on a per-machine basis at the owner's discretion. For security reasons, this configuration setting cannot be changed remotely. To modify it, run the following command locally while the host is offline:

host> config set host.allow_remote_updates true/false

The controller also supports remote updates, following the same logic. The corresponding commands are:

ctl> controller update [--all] [--restart]
controller> config set controller.allow_remote_updates true/false

Mark restart required

ctl> host mark-restart-required <host>

Marks the host as requiring a restart, the same way a plugin update does. Use it after installing or changing a plugin by other means than host plugin install, such as a plugin checked out into external_plugins. The mark shows up in the web interface on the next system metrics poll. The controller has the same command:

ctl> controller mark-restart-required

Instances

List Instances

ctl> instance list [--templates]

List instances. Templates are only listed if --templates is passed.

Create instance

ctl> instance create <name> [--id <instance id>] [--from <instance id>] [--template <instance>] [--as-template]

Create a new instance. name is the instance name. --id is the optional id. --from copies the config of an existing instance. --template makes the new instance inherit all config values from the given template. --as-template creates the instance as a template, see instance.is_template in the configuration docs. Use --as-template --from <instance> to make a template out of an existing instance.

Delete instance

ctl> instance delete <instance>

Deletes the instance and all its files, including saves, from the host it is assigned to. The instance must be stopped, and can not be deleted while it is the template of other instances.

Start instance

ctl> instance start <instance> [--save <name>] [--keep-open]

Starts the instance, which must be assigned to a host. Loads the given save, or the most recently modified save if --save is not passed. --keep-open keeps clusterioctl running and prints the log of the instance until it is stopped with Ctrl+C.

Restart instance

ctl> instance restart <instance> [--save <name>] [--keep-open]

Stops the instance if it is running and starts it again, takes the same options as start.

Load scenario

ctl> instance load-scenario <instance> <scenario> [--seed <seed>] [--map-exchange-string <string>] [--map-gen-settings <file>] [--map-settings <file>] [--keep-open]

Starts the instance with a new game from the given scenario, for example base/freeplay. This only works with save patching turned off for the instance with factorio.enable_save_patching, see Save Patching. --map-exchange-string sets the map generation from a map exchange string copied from Factorio. --map-gen-settings and --map-settings take paths to the JSON files Factorio uses for these, and --seed overrides the seed in them.

Stop instance

ctl> instance stop <instance>

Saves the game and stops the instance.

Start all instances

ctl> instance start-all [--force]

Starts every stopped instance that is assigned to a host. Instances with instance.exclude_from_start_all set are skipped unless --force is passed.

Stop all instances

ctl> instance stop-all

Stops every running instance.

Send RCON command

ctl> instance send-rcon <instance> <command>

Sends a command to the Factorio server of a running instance and prints the reply, for example ctl> instance send-rcon "My World" /players. Quote the command if it contains spaces.

Export data

ctl> instance export-data <instance>

Exports the item icons, names and mod settings from Factorio for the mod pack the instance uses, and uploads them to the controller. The instance must be stopped. The web interface needs this data to show icons and names of items, and to show the settings of the mods in a mod pack. See Exporting data for when to run it.

Kill instance

ctl> instance kill <name>

Terminates the running Factorio server without giving it a chance to save or cleanup after itself.

Note: This may cause loss of data.

Save game

ctl> instance save-game <name>

Saves the running game of the instance to the save it was started from and waits for the save to finish.

Extract players from instance

ctl> instance extract-players <name>

Creates a user account in the cluster for each player that has been online on the currently running save of the instance and sets the online time of that account on this instance to the online time recorded in the save.

Useful when importing a save to a cluster. Note that the online time in a save is recorded differntly from how Clusterio records online time. Most notably Clusterio records wall clock time while the save time is recorded in ticks and this extraction of player time assumes the game runs at 60 ticks a second.

Config management

List Configuration

ctl> instance config list <instance>

List config values for an instance. instance is the instance whose config values to list. Values inherited from a template are marked with (inherited), object fields also list the properties set on the instance.

Set config value

ctl> instance config set <instance> <field> [value] [--stdin]

Set field in instance config. instance is instance to set. field is field to set. value is value to set in field. --stdin signals to read value from stdin.

Set config property of field

ctl> instance config set-prop <instance> <field> <prop> [value] [--stdin]

Set one property of an object field, like factorio.settings, without replacing the rest of the object. value is parsed as JSON if it can be, otherwise it is used as a string. If value is left out the property is removed. For example, to set the max player count and remove the game password:

ctl> instance config set-prop "My World" factorio.settings max_players 16
ctl> instance config set-prop "My World" factorio.settings game_password

Inherit config value

ctl> instance config inherit <instance> <field> [prop]

Make a field in the instance config take its value from the template again, undoing a previous set. instance is the instance to update, field is the field to inherit, prop limits it to one property of an object field.

Edit instance config

ctl> instance config edit <instance> [editor]

Edit instance config in a text editor. Once file is saved and editor has been exited, changed config values will be read back in. instance is the instance to edit, editor is the editor to use. If editor is not given, clusterioctl will read from the EDITOR or VISUAL enviroment variables.

Assign instance to host

ctl> instance assign <instance> [host]

Assigns instance to host. instance is instance to assign, host is host to assign to. If host is not provided, instance will be unassigned.

Saves

Saves are stored on the host the instance is assigned to. The commands below need the instance to be assigned, and the host to be connected.

List saves

ctl> instance save list <instance>

Lists the saves of the instance. loadByDefault marks the save that is loaded when the instance is started without --save.

Create save

ctl> instance save create <instance> [name] [--seed <seed>] [--map-exchange-string <string>] [--map-gen-settings <file>] [--map-settings <file>]

Creates a new save with a freshly generated map without starting the server. The name defaults to world.zip. The map options work the same as for load-scenario.

Upload save

ctl> instance save upload <instance> <file> [--name <name>]

Uploads a save from this computer to the instance. --name gives it a different name on the host, the name must end with .zip. If a save with the same name exists the upload is stored under a new name.

Download save

ctl> instance save download <instance> <save>

Downloads a save from the instance to the current directory.

Rename save

ctl> instance save rename <instance> <old-name> <new-name>

Copy save

ctl> instance save copy <instance> <source> <destination>

Copies a save within the same instance.

Transfer save

ctl> instance save transfer <source-instance> <source-save> <target-instance> [target-save] [--copy]

Moves a save to another instance, which can be on a different host. --copy leaves the original in place. If a save with the target name exists the transferred save is stored under a new name, which is printed.

Delete save

ctl> instance save delete <instance> <save>

Users

Clusterio automatically creates user accounts for all players that join an instance when save patching is enabled. These accounts are used to store per player data shared between instances, like if the player should be whitelisted, admin or banned.

List users

ctl> user list [--attributes] [--stats]

Lists all user accounts in the cluster along with some data for each. --attributes adds the admin, whitelisted and banned status, and --stats adds online time and join counts.

Show user

ctl> user show <name> [--instance-stats]

Shows the account data of one user. --instance-stats adds the online time and join count for each instance.

Create User

ctl> user create <name>

Creates a new empty user account for the given Factorio player. Note that case matters here. This is usually not required as user accounts are created automatically for players that join instances with save patching enabled.

Promote User to Server Admin

ctl> user set-admin <name> [--revoke] [--create]

Promotes the user given to in-game admin on instances with the sync_adminlist option enabled. If the --revoke switch is used the user is removed from the adminlist.

Since admin status is a part of the account data the account must exist for this to succeed, passing --create will create the account if it does not exist.

Note: Being a server admin does not grant any access to manage the cluster. See set-roles for adding roles which grant access to managing the clusetr.

Whitelist User

ctl> user set-whitelisted <name> [--remove] [--create]

Add the user given to the whitelist on instances with the sync_whitelist option enabled. If the --remove switch is used the user is removed from the whitelist.

Since whitelisted status is a part of the account data the account must exist for this to succeed, passing --create will create the account if it does not exist.

Ban User

ctl> user set-banned <name> [--reason <message>] [--pardon] [--create]

Ban user in-game from instances with the sync_banlist option enabled. Reason is a message that will be shown to the user when attemption to log in. If the --pardon switch is used it removes the ban.

Since ban status is a part of the account data the account must exist for this to succeed, passing --create will create the account if it does not exist.

Note: This bans the user from logging in to Factorio servers in the cluster, it does not revoke access to any cluster management they might have, see next section on setting roles for revoking tha.

Bulk importing admin, whitelist and ban lists

Admin lists, whitelists and banlists can be bulk imported with the following command:

ctl> user import <file> [--admins|--whitelist|--bans|--users]

The admin list and whitelist files should be a JSON array of names, the same format as Factorio's server-adminlist.json and server-whitelist.json:

["joe", "bob", "allan"]

The banlist file uses the format of Factorio's server-banlist.json, where each entry is either a name or an object with a username and reason:

[
    "joe",
    {"username": "bob", "reason": "stole materials"},
    {"username": "allan", "reason": "rude language"}
]

The --users option imports a file written by user export, which holds the admin, whitelist and ban status of every user. If no option is given the type is guessed from the file, files with an export_version field are treated as user exports, otherwise the file name must contain ban, admin or whitelist. Users that do not exist are created. Importing only adds to the existing lists, it never removes anyone from them.

To replace a list instead, use restore:

ctl> user restore <file> [--admins|--whitelist|--bans|--users] [--no-backup]

This takes the same files as import, but removes everyone not in the file from the list. The previous list is written to <type>-backup.json in the current directory unless --no-backup is passed.

The current lists can be exported with the following command:

ctl> user export <file> [--admins|--whitelist|--bans|--users]

Defaults to exporting users.

Set Cluster Roles

ctl> user set-roles <name> [roles...]

Replaces the roles the user has in the cluster with a new list of roles. Calling with an empty roles argument will remove all roles from the user.

By default there's a roled named Cluster Admin which grants access to everything and a role named Player which grants a limited read access to the cluster, see the section on roles for more information about setting up roles and permissions.

Revoke user token

ctl> user revoke-token <name>

Makes every authentication token issued to the user stop working, including the one used by the web interface and clusterioctl. The user has to log in again, or be given a new token with npx clusteriocontroller bootstrap generate-user-token <name>. Revoking the token of another user needs the core.user.revoke_other_token permission.

Delete user

ctl> user delete <name>

Deletes everything stored on the controller for this user.

Note: If the player is banned from the cluster this will effectively unban them, as the ban status is stored with the user account.

Note: If the player joins the cluster again a new account will be made for them automatically.

Roles

Access to manage the cluster is granted through roles. A role is a named set of permissions, and a user has the permissions of all the roles they have. By default there are two roles: Cluster Admin, which has the core.admin permission that grants everything, and Player, which can view most of the cluster but not change it. New users get the Player role, this is set by controller.default_role_id. Use user set-roles to give roles to a user.

List roles

ctl> role list

Lists the roles with their ID, description and permissions.

Create role

ctl> role create <name> [--description <text>] [--permissions <permission>]...

Creates a new role and prints its ID. Pass --permissions once for each permission the role should grant, for example:

ctl> role create "Instance Operator" --permissions core.instance.start --permissions core.instance.stop

Edit role

ctl> role edit <role> [--name <name>] [--description <text>] [--set-perms <permission...>] [--add-perms <permission...>] [--remove-perms <permission...>] [--grant-default]

Changes the name, description or permissions of a role. --set-perms replaces the permissions of the role, --add-perms and --remove-perms change them, and these take several permissions separated by spaces. --grant-default adds the permissions shown as granted by default in permission list, which are the ones the Player role starts with.

Delete role

ctl> role delete <role>

Deletes the role, users that had it lose the permissions it granted.

Permissions

List permissions

ctl> permission list

Lists all permissions with their name, title, description and whether they are granted by default. Plugins can add their own permissions, these show up here when the plugin is loaded on the controller.

Mods

Mods are stored on the controller and sent to hosts when an instance needs them.

List mods

ctl> mod list [--fields <field...>]

Lists the mods stored on the controller. --fields picks the columns to show, --fields all shows every field.

Search mods

ctl> mod search <factorio-version> [query] [--page <n>] [--page-size <n>] [--sort <field>] [--sort-order asc|desc] [--fields <field...>]

Searches the mods stored on the controller that work with the given major version of Factorio, for example 2.0. This does not search the Factorio Mod Portal, use the Mods page of the web interface for that.

Show mod

ctl> mod show <name> <version>

Shows the details of a stored mod.

Upload mod

ctl> mod upload <file>

Uploads a mod zip file to the controller.

Download mod

ctl> mod download <name> <version>

Downloads a stored mod to the current directory.

Delete mod

ctl> mod delete <name> <version>

Deletes a stored mod from the controller.

Mod Packs

A mod pack is a list of mods with their versions and mod settings, see Mod packs.

List mod packs

ctl> mod-pack list

Show mod pack

ctl> mod-pack show <mod-pack>

Shows the mods and settings of a mod pack.

Create mod pack

ctl> mod-pack create <name> <factorio-version> [--description <text>] [--mods <name:version...>] [--disabled-mods <name...>] [--bool-setting <scope> <name> <value>] ...

Creates a mod pack for the given version of Factorio and prints its ID. The built in mods of Factorio, like base and space-age, are added automatically with only base enabled. Mods are given as name:version, and optionally name:version:sha1. --disabled-mods takes the names of mods from --mods that should be in the pack but not enabled. Mod settings are set with --bool-setting, --int-setting, --double-setting, --string-setting and --color-setting, which each take a scope, a setting name and a value. The scope is one of startup, runtime-global or runtime-per-user, and a color is given as JSON like {"r":1,"g":0,"b":0,"a":1}.

Edit mod pack

ctl> mod-pack edit <mod-pack> [--name <name>] [--description <text>] [--factorio-version <version>] [--add-mods <name:version...>] [--enable-mods <name...>] [--disable-mods <name...>] [--remove-mods <name...>] [--<type>-setting <scope> <name> <value>] [--remove-setting <scope> <name>]

Changes a mod pack, the options work the same as for create. --add-mods also replaces the version of a mod already in the pack. Mods are not checked against the mods stored on the controller, make sure the mods you add have been uploaded.

Export and import mod packs

ctl> mod-pack export <mod-pack>
ctl> mod-pack import <string>

export prints the mod pack as a string, and import creates a new mod pack from such a string. This is the same string as the Import string button and the Export to string action in the web interface use.

Delete mod pack

ctl> mod-pack delete <mod-pack>

Notes

Free text notes can be attached to hosts, instances, users, roles, mod packs, mods and saves. They are stored on the controller and shown to everyone with access to the resource in the web interface, and can for example be used to record who runs a host or what an instance is meant for.

The web interface renders notes as Markdown. A mention of the form @<type>/<id> becomes a link to that resource showing its name, for example @instance/778528005 or @user/cooldude2606. This works for hosts, instances, users, roles and mod packs, and the id is shown if the name is not available. The note itself stores the mention as written.

List notes

ctl> note list [--type <type>]

Lists all notes, optionally limited to one resource type.

Set note

ctl> note set <type> <id> <content>

Sets the note of a resource. The type is one of host, instance, user, role, mod_pack, mod or save. The id is the numeric id for hosts, instances, roles and mod packs, the lower case name for users, <name>_<version> for mods and <instance id>/<file name> for saves.

Delete note

ctl> note delete <type> <id>

Removes the note of a resource. Notes are also removed when the resource they are attached to is deleted.

Logs

Query log

ctl> log query [--all] [--controller] [--host <host>] [--instance <instance>] [--max-level <level>] [--limit <n>] [--start]

Prints entries from the cluster log stored on the controller. At least one of --all, --controller, --host and --instance must be passed to pick which logs to read. --max-level leaves out entries less important than the given level, for example warn. Prints the last 1000 entries by default, --limit changes the number and --start takes them from the start of the log instead.

Follow log

ctl> log follow [--all] [--controller] [--host <host>] [--instance <instance>]

Prints new log entries as they come in until stopped with Ctrl+C. Takes the same options for picking logs as query.

Plugins (Local)

The plugins loaded by clusterioctl are managed with the plugin command, which works without a connection to the controller. See the readme for @clusterio/ctl.

Plugins (Remote)

The installer asks "Allow remote updates and plugin installs from the web interface?" and the answer sets allow_remote_updates, allow_plugin_updates and allow_plugin_install together on that machine, pass --remote-npm or --no-remote-npm to answer it from the command line. Remote updates allow ctl and the web UI to update Clusterio and plugins on machines within the cluster. Remote installs allow them to install any package from npm onto the machine, which is a risk of arbitrary code execution through malicious npm packages, so only allow them if you trust everyone with access to install plugins. In a config created without the installer remote updates are enabled and remote installs are disabled by default. See below for changing these settings after installing.

List

ctl> controller plugin list
ctl> host plugin list <host>

This command lists all plugins currently known to the remote. Newly installed plugins will not be displayed until the remote is restarted. Plugins that are distributed as an npm package can be updated remotely.

Update

ctl> controller plugin update <name>[@<version>] [--restart]
ctl> host plugin update <host> <name>[@<version>] [--restart]

If remote plugin updates are enabled on the remote, this will execute npm update --save <name>, which stays within the version range saved in the remote's package.json. To update to a specific version, including one outside that range, pass it as <name>@<version>, for example @clusterio/plugin-example@2.1.0. The version must be published on npm, and the remote then executes npm install --save <name>@<version>. The plugin must already be installed on the remote, and only remote plugin updates need to be enabled. Changes will not be applied until the remote is restarted. If the --restart flag is provided, the remote will automatically restart once the update is complete.

Update All

ctl> controller update --all [--restart]
ctl> host update <host> --all [--restart]

Updates the Clusterio package and all plugins installed from npm in a single npm update --save command. Updating everything at once avoids ending up with multiple versions of @clusterio/lib in the installation. Requires both remote updates and remote plugin updates to be enabled on the remote.

Install

ctl> controller plugin install <name>[@<version>] [--restart]
ctl> host plugin install <host> <name>[@<version>] [--restart]

If remote plugin installs are enabled on the remote, this will execute npm install --save <name>. Pass <name>@<version> to install a specific version, for example to match the version used by the rest of the cluster. The package, and the version if given, must be published on npm. Changes will not be applied until the remote is restarted. If the --restart flag is provided, the remote will automatically restart once the update is complete.

ctl> controller plugin search [query] [--page <n>] [--page-size <n>]

Searches the npm registry for packages tagged with the clusterio-plugin keyword. The search is done by the controller and does not require remote installs to be enabled. The web UI has a plugin browser on the plugins page that uses the same search.

Concurrent Operations

Only one npm operation runs at a time on a machine. A standalone controller and host share their working directory, so the operation holds the npm-operation.lock file there while npm runs. Other installs and updates on the same machine or installation are rejected with "Another package operation is already in progress on this machine" until it finishes. A lock file left behind by a process that is no longer running is removed automatically.

Enable/Disable Updates

host> config set host.allow_plugin_updates true/false
controller> config set controller.allow_plugin_updates true/false

Remote updates are enabled by default but can be disabled on a per-machine basis at the owner's discretion. For security reasons, this configuration setting cannot be changed remotely. To modify it, run the above commands locally while the remote is offline.

Enable/Disable Installs

host> config set host.allow_plugin_install true/false
controller> config set controller.allow_plugin_install true/false

Remote installs are disabled by default but can be enabled on a per-machine basis at the owner's discretion. For security reasons, this configuration setting cannot be changed remotely. To modify it, run the above commands locally while the remote is offline.

Prometheus Metrics

The controller exports metrics for the whole cluster on the /metrics endpoint. Fetching it requires a token for a user with the core.controller.metrics permission, sent either as an Authorization: Bearer <token> header or as an X-Access-Token header. Requests without a valid token get a 401 response and requests for users lacking the permission get a 403 response.

Create a role with just this permission, a user to hold it, and generate a token for that user. Give the user a name that is not a valid Factorio player name, such as one starting with #, so a player joining the cluster can never claim the account and its token:

ctl> role create Prometheus --permissions core.controller.metrics
ctl> user create #prometheus
ctl> user set-roles #prometheus Prometheus
$ npx clusteriocontroller bootstrap generate-user-token '#prometheus'

Then pass the token in the scrape job for the controller in prometheus.yml:

scrape_configs:
  - job_name: clusterio
    authorization:
      credentials: <token>
    static_configs:
      - targets: ["localhost:8080"]

Concurrent scrapes share a single round of metrics gathering from the hosts, so multiple scrapers polling the controller do not multiply the load on the hosts.