2.0.0-alpha.23

Merge pull request #868 from Hornwitser/small-things-16
Small things 16
2026-11-11 23:04:52 +09:00 · 2026-03-10 19:03:18 +00:00 · 2026-03-10 02:51:31 +01:00 · 2026-03-10 01:50:00 +00:00 · 2026-03-10 02:35:09 +01:00 · 2026-03-10 02:19:01 +01:00
375 changed files with 31017 additions and 7033 deletions
@@ -0,0 +1,4 @@
+{
+	"image":"mcr.microsoft.com/devcontainers/universal:2",
+	"postCreateCommand": "mkdir factorio && cd factorio && wget https://factorio.com/get-download/1.1.107/headless/linux64 && tar -xf linux64 && mv factorio factorio_1.1.107 && rm linux64 && wget https://factorio.com/get-download/2.0.47/headless/linux64 && tar -xf linux64 && mv factorio factorio_2.0.47 && rm linux64 && pnpm install",
+}
@@ -1 +0,0 @@
-dist/
@@ -0,0 +1,17 @@
+Describe why and what has been changed by this pullrequest, feel free to also ask for input on decisions you are unsure about etc.
+The changelog lines below will be copied directly from merged pull requests to the changelog on new releases. Changes are expected to preferrentially link to the associated issues. If there are no relevant issues, link to the pull request itself.
+
+## Changelog
+```
+### Features
+- Added doodad to web interface. [#999](https://github.com/clusterio/clusterio/issues/999)
+
+### Changes
+- ...
+
+### Fixes
+- ...
+
+### Breaking changes
+- ...
+```
@@ -12,41 +12,66 @@ jobs:
    runs-on: ubuntu-latest
    strategy:
      matrix:
-        node-version: [18.x, 20.x]
-        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
+        # Supported versions are active lts and maintenance see https://nodejs.org/en/about/releases/
+        node-version: [20.x, 22.x]
+        # Supported versions are latest stable and one minor version before stable (even if from a previous major) 
+        factorio-version: [1.1.110, 2.0.47]

    steps:
-    - uses: actions/checkout@v3
-    - uses: pnpm/action-setup@v2.4.0
-      with:
-        version: 8
+    - uses: actions/checkout@v4
+    - uses: pnpm/action-setup@v4
    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v3
+      uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
-    - run: pnpm i --no-optional --no-frozen-lockfile
-    - run: wget -q -O factorio.tar.gz https://www.factorio.com/get-download/latest/headless/linux64 && tar -xf factorio.tar.gz && rm factorio.tar.gz
+    - name: Prepare and install
+      run: pnpm i --no-frozen-lockfile
+    - name: Use Factorio ${{ matrix.factorio-version }}
+      run: wget -q -O factorio.tar.gz https://www.factorio.com/get-download/${{ matrix.factorio-version }}/headless/linux64 && tar -xf factorio.tar.gz && rm factorio.tar.gz
    - name: Run tests
-      if: ${{ matrix.node-version != '18.x' }}
+      if: ${{ matrix.node-version != '20.x' || matrix.factorio-version != '1.1.110' }}
      run: pnpm test
    - name: Run coverage
-      if: ${{ matrix.node-version == '18.x' }}
+      if: ${{ matrix.node-version == '20.x' && matrix.factorio-version == '1.1.110' }}
      run: pnpm run ci-cover
    - name : Upload coverage to Codecov
-      if: ${{ matrix.node-version == '18.x' }}
-      uses: codecov/codecov-action@v2
+      if: ${{ matrix.node-version == '20.x' && matrix.factorio-version == '1.1.110' }}
+      uses: codecov/codecov-action@v4
      with:
        files: ./coverage/lcov.info
+        token: ${{ secrets.CODECOV_TOKEN }}
+    - name: Upload test logs for debugging
+      if: ${{ !cancelled() }}
+      uses: actions/upload-artifact@v4
+      with:
+        name: logs-${{ matrix.node-version }}-${{ matrix.factorio-version }}
+        path: temp/test/logs

  lint:
    runs-on: ubuntu-latest
    steps:
-    - uses: actions/checkout@v3
-    - uses: pnpm/action-setup@v2.4.0
+    - uses: actions/checkout@v4
+    - uses: pnpm/action-setup@v4
+    - uses: actions/setup-node@v4
      with:
-        version: 8
-    - uses: actions/setup-node@v3
-      with:
-        node-version: 18.x
-    - run: pnpm i --no-optional --no-frozen-lockfile
+        node-version: 20.x
+    - run: pnpm i --no-frozen-lockfile
    - run: pnpm run lint
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - uses: pnpm/action-setup@v4
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 20.x
+    - run: pnpm i --no-frozen-lockfile
+    - run: pnpm run build-mod
+    # Upload build to artifacts
+    - name: Upload build to artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: clusterio_lib
+        path: ./dist
+        if-no-files-found: error
@@ -0,0 +1,48 @@
+
+name: Publish
+
+on:
+  release:
+    types:
+      - released
+
+jobs:
+  npm:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 8
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          registry-url: https://registry.npmjs.org
+      - run: pnpm install --no-frozen-lockfile
+      - run: pnpm -r --filter='./{plugins,packages}/*' publish --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: $${{ secrets.NPM_TOKEN }}
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: pnpm-lock.yaml
+
+  factorio:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 8
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+      - run: pnpm install --no-frozen-lockfile
+      - run: pnpm -r --filter='./{plugins,packages}/*' run build-mod --output-dir ../../dist
+      - run: node ./publish.js factorio ./dist
+        env:
+          FACTORIO_TOKEN: ${{ secrets.FACTORIO_TOKEN }}
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: ./dist/*
@@ -29,15 +29,13 @@ dist/

 node_modules

-Factorio*
-/factorio
+/factorio*
 /instances
 /mods
 /database
 /plugin-list.json
-/config-controller.json
-/config-control.json
-/config-host.json
+/config-*.json
+/config-*.json.lock
 pnpm-lock.yaml
 mod_cache.json
 /static/
@@ -1,5 +1,330 @@
 # Changelog

+<!-- Template for entries. Add sections that apply as changes are made.
+## Version 2.0.0-alpha.xx
+
+### Major Features
+
+- Major additions and/or major improvements to managing clusters.
+
+### Features
+
+- New features added.
+
+### Changes
+
+- Small changes to existing behaviour.
+
+### Fixes
+
+- Bugfixes
+
+### Breaking Changes
+
+- Changes which break backwards compatibility with older hosts or plugins code.
+
+### Meta
+
+- Changes to the project activities / structure worth highlighting but have no impact on the published package.
+
+Many thanks to the following for contributing to this release:  
+[@username](https://github.com/username)
+-->
+
+## Version 2.0.0-alpha.23
+
+### Major Features
+
+- Added automatic headless download and update on linux. [#330](https://github.com/clusterio/clusterio/issues/330)
+- Added recipe notification sync to inventory sync. [#506](https://github.com/clusterio/clusterio/issues/506)
+
+### Features
+
+- Added config lock files to prevent process duplication. [#815](https://github.com/clusterio/clusterio/issues/815)
+- Added process and system start times to system metrics. [#826](https://github.com/clusterio/clusterio/issues/826)
+- Added icons to status tags for host and instances. [#827](https://github.com/clusterio/clusterio/issues/827)
+- Extended export-data to produce separate spritesheets for recipes, signals, technologies, planets, qualities, entities, and static UI icons. [#838](https://github.com/clusterio/clusterio/pull/838)
+- Added Icon Reference page to web interface at `/icon-reference` for browsing all exported icons. [#838](https://github.com/clusterio/clusterio/pull/838)
+- Added visual flash to RCON result box to confirm command execution, even when the output is identical to the previous result. [#793](https://github.com/clusterio/clusterio/issues/793)
+
+### Changes
+
+- Login screen now displays the cluster name. [#818](https://github.com/clusterio/clusterio/issues/818)
+- Instance versions can now be set using Major.Minor without specifing a patch version. [#820](https://github.com/clusterio/clusterio/issues/820)
+- Versions for factorio and modpacks can now be selected using a drop down menu. [#820](https://github.com/clusterio/clusterio/issues/820)
+- The controller will now refuse to start if no users were loaded from file. [#814](https://github.com/clusterio/clusterio/issues/814)
+- Improved wording and display of the generate host token modal. [#828](https://github.com/clusterio/clusterio/issues/828)
+- Installations where muliple conflicting clusterio/lib packages have been installed will now fail with an error [#863](https://github.com/clusterio/clusterio/issues/863).
+- Export completion now logs per-category icon counts. [#838](https://github.com/clusterio/clusterio/pull/838)
+
+### Fixes
+
+- Removed debug log statement from equipment grid serialization. [#XXX](https://github.com/clusterio/clusterio/pull/XXX)
+- Fix that the documentation had a dead link to details of the message passing protocol (#812)
+- Fixed case where achievements were not disabled. [#817](https://github.com/clusterio/clusterio/pull/817)
+- Fix headless download on linux install. [#815](https://github.com/clusterio/clusterio/issues/816)
+- Fix option `--no-download-headless` being ignored. [#815](https://github.com/clusterio/clusterio/issues/816)
+- Fixed action buttons overflowing on narrow screens across the web interface. [#810](https://github.com/clusterio/clusterio/issues/810)
+- Fixed player logistics failing to load on servers without unlocked logistics networks. [#1234](https://github.com/clusterio/clusterio/issues/1234)
+- Fixed mod dependency parser breaking with inconsistent spaces. [#834](https://github.com/clusterio/clusterio/issues/834)
+- No longer attempts to sync inventory in single player. [#835](https://github.com/clusterio/clusterio/issues/835)
+- Fixed tests failing when the configured factorio_directory contains stuff other than Factorio installs [#540](https://github.com/clusterio/clusterio/issues/540).
+- Always create a whitelist file so it can be watched for changes. [#865](https://github.com/clusterio/clusterio/issues/865)
+- Added missing await statements which could cause an instance to start with an outdated admin/ban/whitelist. [#869](https://github.com/clusterio/clusterio/issues/869)
+- Fixed metrics breaking when labels contain comma or equal signs [#861](https://github.com/clusterio/clusterio/issues/861)
+- Fixed Host page show repeated errors when viewing an offline local host [#848](https://github.com/clusterio/clusterio/issues/848)
+- Fixed bad mod paths in icon specifications crashing the export. [#841](https://github.com/clusterio/clusterio/issues/841)
+- Fixed prototypes with no icon data causing errors during export. [#841](https://github.com/clusterio/clusterio/issues/841)
+
+### Breaking Changes
+
+- Custom permission methods should use `IUser` rather than `IControllerUser` [#837](https://github.com/clusterio/clusterio/pull/837)
+- `controller.userManager` has been refactored, see PR for details. [#837](https://github.com/clusterio/clusterio/pull/837)
+- `controller.instances` has been refactored, see PR for details. [#837](https://github.com/clusterio/clusterio/pull/837)
+- `User/Instance/HostInfo` renamed to `User/Instance/HostRecord` [#837](https://github.com/clusterio/clusterio/pull/837)
+- Removed `host.tls_ca` and `control.tls_ca` config options, see [section on self signed certificates](https://github.com/clusterio/clusterio/blob/master/docs/setting-up-tls.md#creating-and-using-a-self-signed-certificate) for the replacement for this option [#857](https://github.com/clusterio/clusterio/issues/857)
+
+Many thanks to the following for contributing to this release:  
+[@Cooldude2606](https://github.com/Cooldude2606)
+[@Daniel](https://github.com/Danielv123)
+[@Double](https://github.com/DoubleThoughtTheProgrammer)
+[@Hornwitser](https://github.com/Hornwitser)
+[@Ryan Walker](https://github.com/solarcloud7)
+
+## Version 2.0.0-alpha.22
+
+### Major Features
+
+- Added a download dependencies button which downloads missing dependencies. [#726](https://github.com/clusterio/clusterio/issues/726)
+- Added an update mod button which downloads the latest compatible version of a mod. [#725](https://github.com/clusterio/clusterio/issues/725)
+
+### Features
+
+- Added online player list to instance details page. [#666](https://github.com/clusterio/clusterio/issues/666)
+- Added ability to restart instances as a single action. [#779](https://github.com/clusterio/clusterio/issues/779)
+- Added ability to exclude instances from the 'Start all' web UI button. [#451](https://github.com/clusterio/clusterio/issues/451)
+- Added plugin update detection for restart required [#759](https://github.com/clusterio/clusterio/issues/759)
+- Added detection for mismatched mod and mod pack factorio version. [#727](https://github.com/clusterio/clusterio/issues/727)
+- Added detection for dependency issues such as incompatible or wrong version. [#727](https://github.com/clusterio/clusterio/issues/727)
+- Added a quick fix button for resolving detected dependency issues. [#801](https://github.com/clusterio/clusterio/issues/801)
+
+### Changes
+
+- Restart host / controller is now the default action with stop moved to a dropdown. [#780](https://github.com/clusterio/clusterio/issues/780)
+- Restart host / controller no longer shows unless it is enabled for that machine. [#780](https://github.com/clusterio/clusterio/issues/780)
+- Plugin templates no longer depend on a dev install of Clusterio. [#786](https://github.com/clusterio/clusterio/issues/786)
+- Better error message for when a plugin is missing an index file. [#799](https://github.com/clusterio/clusterio/pull/799)
+- `ModStore.downloadMods` no longer checks if the mod is already downloaded. [#801](https://github.com/clusterio/clusterio/issues/801
+- Mod version for buildins will always be fully qualified, matching the requirement enforced on other mods. [#801](https://github.com/clusterio/clusterio/issues/801))
+- Subscriptions can now be filtered. [#788](https://github.com/clusterio/clusterio/pull/788)
+
+### Fixes
+
+- Fixed the missing space between action buttons on the users and hosts list. [#780](https://github.com/clusterio/clusterio/issues/780)
+- Fixed "rendered more hooks" error when refreshing hosts page. [#769](https://github.com/clusterio/clusterio/issues/769)
+- Fixed inventory combinator time signal not always updating [#610](https://github.com/clusterio/clusterio/issues/610)
+- Renamed templates for `.gitignore` and `.npmignore` that caused `create --plugin-template` to fail. [#800](https://github.com/clusterio/clusterio/pull/800)
+- Fixed npm update button failing to apply update and restart.
+
+### Breaking changes
+
+- `ModPortalDownloadRequest` now requires an array of mod version pairs rather than a single mod name and version. [#801](https://github.com/clusterio/clusterio/issues/801)
+- Version strings (e.g. `1.0`, `1.0.0`) now have stricter typing and validation, passing unchecked strings to functions will error. [#801](https://github.com/clusterio/clusterio/issues/801)
+
+Many thanks to the following for contributing to this release:  
+[@Cooldude2606](https://github.com/Cooldude2606)
+[@Danielv123](https://github.com/Danielv123)
+[@Hornwitser](https://github.com/Hornwitser)
+
+## Version 2.0.0-alpha.21
+
+### Major Features
+
+- Added import, export, and restore of user lists (bans / admins / whitelist / combined). [#717](https://github.com/clusterio/clusterio/issues/717)
+- Added remote update for core packages and third party plugins. [#761](https://github.com/clusterio/clusterio/issues/761)
+- Added config cloning on instance creation. [#720](https://github.com/clusterio/clusterio/issues/720)
+
+### Features
+
+- Added social links and instructions to error page. [#742](https://github.com/clusterio/clusterio/issues/742)
+- Added button to download control config. [#740](https://github.com/clusterio/clusterio/issues/740)
+- Added server action filter (aka "chat filter") to instance log in web ui. [#744](https://github.com/clusterio/clusterio/issues/744)
+- Added `factorio.console_logging` to enable dedicated console log file for servers. [#748](https://github.com/clusterio/clusterio/issues/748)
+- Added a recovery mode to host and controller accessible as an option on the run command. [#752](https://github.com/clusterio/clusterio/issues/752)
+- Added username search to the users list. [#751](https://github.com/clusterio/clusterio/issues/751)
+- Added log level filtering to the web ui. [#745](https://github.com/clusterio/clusterio/issues/745)
+- Added pending update detection for host and controller. [#758](https://github.com/clusterio/clusterio/issues/758)
+- Added restart required indicator for host and controller. [#758](https://github.com/clusterio/clusterio/issues/758)
+- Added version mismatch indicator in host list. [#758](https://github.com/clusterio/clusterio/issues/758)
+- Added host plugin list command to crl where previously only controller plugin list existed. [#760](https://github.com/clusterio/clusterio/issues/760)
+- Added optional feature which allows new plugins to be installed remotely.
+- Added bidirectional whitelist syncing. [#716](https://github.com/clusterio/clusterio/issues/716)
+- Added support for v2 map exchange strings. [#700](https://github.com/clusterio/clusterio/issues/700)
+
+### Fixes
+
+- Fixed handling of zip files with multiple top-level folders. [#739](https://github.com/clusterio/clusterio/issues/739)
+- Fixed looping between instances of ban and admin sync events. [#736](https://github.com/clusterio/clusterio/issues/736)
+- Fixed quality being stripped from power armour equipment when moving between servers [#753](https://github.com/clusterio/clusterio/pull/753)
+- Resolved webpack type export warnings [#750](https://github.com/clusterio/clusterio/pull/750)
+- Reduce page load time on users list by enabling pagination. [#718](https://github.com/clusterio/clusterio/issues/718)
+- Corrected stack trace and enabled source mapping during bootstrap. [#764](https://github.com/clusterio/clusterio/pull/764)
+- Fixed map gen settings using the incorrect name for cliff settings following exchange string decode.
+
+### Meta
+
+- Silent testing is now truly silent. [#764](https://github.com/clusterio/clusterio/pull/764)
+- Node 18 has reached end of life and is no longer maintained, we no longer guarantee support for it.
+- CI testing now runs on node 20 & 22 as well as factorio 1.1.110 & 2.0.47.
+
+Many thanks to the following for contributing to this release:  
+[@Cooldude2606](https://github.com/Cooldude2606)
+[@Danielv123](https://github.com/Danielv123)
+[@Hornwitser](https://github.com/Hornwitser)
+
+## Version 2.0.0-alpha.20
+
+### Features
+
+- Update subspace storage to 2.0 and space age. [#733](https://github.com/clusterio/clusterio/pull/733)
+- A fresh install of Clusterio will include default mod packs. [#719](https://github.com/clusterio/clusterio/issues/719)
+
+### Fixes
+
+- Fix crash when leaving a server without a logistic requester point [#731](https://github.com/clusterio/clusterio/pull/731)
+- Use floor instead of round to prevent "1 minute and 60 seconds" being shown [#723](https://github.com/clusterio/clusterio/issues/723)
+- Fixed production statistics overwriting consumption statistics and vise versa [#734](https://github.com/clusterio/clusterio/pulls/734)
+- Hot patch to add the updated 2.0.29 control.lua freeplay hash to know scenarios. [commit](https://github.com/clusterio/clusterio/commit/26269df7d4d8f39042c59653008bc8f034a4f3b4)
+
+### Meta
+
+- We have now introduced a new [decisions log](https://github.com/clusterio/clusterio/blob/master/docs/decisions.md) to aid tracking all the technical and design decisions we make and their reasons. [#714](https://github.com/clusterio/clusterio/pull/714)
+
+Many thanks to the following for contributing to this release:  
+[@Cooldude2606](https://github.com/Cooldude2606)
+[@Danielv123](https://github.com/Danielv123)
+[@psihius](https://github.com/psihius)
+
+## Version 2.0.0-alpha.19
+
+### Major Features
+
+- Added support for 2.0 builtin mods during mod pack creation. [#684](https://github.com/clusterio/clusterio/pull/684)
+- Added basic 2.0 support to clusterio lua api and 1st party plugins. [#685](https://github.com/clusterio/clusterio/pull/685)
+
+### Features
+
+- Added Datastore and Datastore Provider classes to the library to support savable Maps. [#629](https://github.com/clusterio/clusterio/pull/629)
+- Added clean script to speed up publishing and debugging of build steps. [#640](https://github.com/clusterio/clusterio/pull/640)
+- Added sub-tile option on plugin page headers. [#642](https://github.com/clusterio/clusterio/pull/642)
+- Greatly improved plugin and module template generation. [#641](https://github.com/clusterio/clusterio/pull/641)
+- Duplicate host connections from the same address will kill the older host process. [#647](https://github.com/clusterio/clusterio/pull/647)
+- Controller will refuse duplicate host connections from different addresses. [#647](https://github.com/clusterio/clusterio/pull/647)
+- Monorepos are now supported for external plugins. [#654](https://github.com/clusterio/clusterio/pull/654)
+- Changed default role selection to be a dropdown menu rather than id. [#664](https://github.com/clusterio/clusterio/pull/664)
+- Added credential option to config entries to allow writing sensitive data that can't be read back remotely.
+- Allow hidden and readonly graphical representations of config values. [#665](https://github.com/clusterio/clusterio/pull/665)
+- Added locale exporting for all builtin mods, not just for the base mod. [#684](https://github.com/clusterio/clusterio/pull/684)
+- Added option for silent testing which only shows the results, can be ran using `pnpm silent-test` [#680](https://github.com/clusterio/clusterio/pull/680)
+- Added prompt for http port on installation of Clusterio. [#564](https://github.com/clusterio/clusterio/issues/564)
+- Added drag and drop overlay to upload button on mods page and save table on instance page. [#591](https://github.com/clusterio/clusterio/issues/591)
+- Automatically add plugins from ./plugins, ./external_plugins and installed npm modules. [#692](https://github.com/clusterio/clusterio/pull/692)
+- `compat.table_to_json` and `compat.json_to_table` supported in all stages in pre 2.0 [#687](https://github.com/clusterio/clusterio/issues/687)
+- Add "connect to server" button to web interface, launches with steam api. [#608](https://github.com/clusterio/clusterio/issues/608)
+- Add space platform name mapping to space platform statistics. [#706](https://github.com/clusterio/clusterio/pull/706)
+- Track space platform speed metric clusterio_statistics_exporter_platform_speed. [#706](https://github.com/clusterio/clusterio/pull/706)
+- Track space platform weight metric clusterio_statistics_exporter_platform_weight. [#706](https://github.com/clusterio/clusterio/pull/706)
+- Added bidirectional sync to admin and ban list. [#709](https://github.com/clusterio/clusterio/pull/709)
+
+### Fixes
+
+- Fixed IPC errors reporting undefined when no stack trace was present. [#624](https://github.com/clusterio/clusterio/pull/624)
+- Fixed loopback routing for instances reporting the wrong error message. [#625](https://github.com/clusterio/clusterio/pull/625)
+- Fixed docs linking to non-existing js files after ts migration. [#633](https://github.com/clusterio/clusterio/pull/633)
+- Fixed CI workflows using deprecated version of nodejs. [#637](https://github.com/clusterio/clusterio/pull/637)
+- Fixed linux only tests to run on windows. [#661](https://github.com/clusterio/clusterio/pull/661)
+- Fixed log events being sent from a host over an invalid websocket. [#639](https://github.com/clusterio/clusterio/pull/639)
+- Fixed spaces passed in arguments to the installer causing it to break. [#620](https://github.com/clusterio/clusterio/issues/620)
+- Fixed numeric admin name breaking login. [#536](https://github.com/clusterio/clusterio/issues/536)
+- Fixed issues with subscriptions which prevented them from working on instances or generic events. [#655](https://github.com/clusterio/clusterio/pull/655).
+- Fixed unreliable datastore tests. [#662](https://github.com/clusterio/clusterio/pull/662).
+- Fixed 2.0 version extraction from linux headless. downloaded during installation of clusterio. [#671](https://github.com/clusterio/clusterio/pull/671)
+- Fixed invalid transient state during server start. [#676](https://github.com/clusterio/clusterio/issues/676)
+- Fixed host user sync to instances after reconnecting to the. controller. [#678](https://github.com/clusterio/clusterio/pull/678)
+- Fixed WebUI adding and displaying the wrong base mod version. [#684](https://github.com/clusterio/clusterio/pull/684)
+- Fixed WebUI inconsistent pattern matching for factorio version. [#684](https://github.com/clusterio/clusterio/pull/684)
+- Fixed `safeOutputFile` not being atomic because of a missing path separator. [#659](https://github.com/clusterio/clusterio/pull/659)
+- Fixed built-in mods showing as missing in the WebUI. [#581](https://github.com/clusterio/clusterio/issues/581)
+- Fixed dirty flag not being set when only the config of an instance is updated. [#675](https://github.com/clusterio/clusterio/pull/675)
+- Fixed incorrect command being used to remove players from the whitelist. [#679](https://github.com/clusterio/clusterio/pull/679)
+- Fixed CI following undocumented breaking change from downstream dependency. [#683](https://github.com/clusterio/clusterio/pull/683)
+- Fixed instance crash when missing saves folder. [#698](https://github.com/clusterio/clusterio/issues/698)
+- Fixed statistics exporter not working on newer versions of windows 11 due to wmic deprecation. [#707](https://github.com/clusterio/clusterio/issues/707)
+
+### Changes
+
+- Added prompt for the HTTP port to host the controller to the installer. [#619](https://github.com/clusterio/clusterio/pull/619)
+- Added tests for sendEvent and sendRequest throwing the correct error messages. [#638](https://github.com/clusterio/clusterio/pull/638)
+- Updated all web ui pages to use correct page header component. [#643](https://github.com/clusterio/clusterio/pull/643)
+- Bumped Typescript version to 5.5 and implemented `${configDir}` in base configs for "outDir". [#648](https://github.com/clusterio/clusterio/pull/648).
+- Added factorio.executable_path option which allows overriding the default path to the Factorio executable run.
+- Added instance version display. [#573](https://github.com/clusterio/clusterio/pull/573)
+- Added `factorio.shutdown_timeout` config to set the time the host will wait for a Factorio server to shut down befor killing it.
+- Changed shutdown logic to prefer sending a /quit command via RCON instead of using diverging logic on Windows and Linux.
+- Added `controller.factorio_username` and `controller.factorio_token` config to set Factorio credentials used for the whole cluster.
+- Added `controller.share_factorio_credential_with_hosts` config to optionally require hosts to provide their own credentials.
+- Added `host.factorio_username` and `host.factorio_token` config to set Factorio credentials used on a given host.
+- Changed `instance.rcon_password` config to be a credential field that can not be read by the control interface.
+- Changed `host.id` `instance.id` and `instance.assign_host` config to be hidden fields that can not be seen on the web ui.
+- Updated display name and description of `controller.external_address` to avoid confusion. [#674](https://github.com/clusterio/clusterio/pull/674)
+- Renamed config value `controller.external_address` to `controller.public_url`, migrations are applied automatically.
+- String config values with whitelisted values (enum) now display as a selection dropdown. [#701](https://github.com/clusterio/clusterio/pull/701)
+- Existing selection dropdowns now support search filtering. [#701](https://github.com/clusterio/clusterio/pull/701)
+- Added surface label to clusterio_statistics_exporter_instance_force_flow_statistics. [#691](https://github.com/clusterio/clusterio/issues/691)
+- Compat lib now supports versions from 0.17 to 2.0 [#711](https://github.com/clusterio/clusterio/pull/711)
+- Add bidirectional sync to admin and ban list. [#709](https://github.com/clusterio/clusterio/pull/709)
+
+### Breaking Changes
+
+- Previously silent errors for controller.sendEvent now throw exceptions [#625](https://github.com/clusterio/clusterio/pull/625).
+- @clusterio/controller export InstanceInfo has added factorioVersion parameter.
+- Argument order for `Config.canAccess` changed to require an access mode passed as the second argument.
+- Instances can now have `factorio.enable_script_commands` disabled which will throw an error when any script command is used over rcon. [#681](https://github.com/clusterio/clusterio/pull/681).
+- User IDs are now case insensitive, duplicate users will be automatically merged with a backup created. [#682](https://github.com/clusterio/clusterio/pull/682)
+- Plugins now require the keyword "clusterio-plugin" in package.json to be automatically loaded [#692](https://github.com/clusterio/clusterio/pull/692)
+
+Many thanks to the following for contributing to this release:  
+[@CCpersonguy](https://github.com/CCpersonguy)
+[@Cooldude2606](https://github.com/Cooldude2606)
+[@Danielv123](https://github.com/Danielv123)
+[@Hornwitser](https://github.com/Hornwitser)
+[@Laar](https://github.com/Laar)
+[@psihius](https://github.com/psihius)
+
+
+## Version 2.0.0-alpha.18
+
+### Features
+
+- Added logging of HTTP requests and errors on the controller [#556](https://github.com/clusterio/clusterio/pull/556).
+- Added caching of data parsed from mods to speed up startup time [#606](https://github.com/clusterio/clusterio/pull/606).
+- Added command to installer to generate the code for making a new plugin [#570](https://github.com/clusterio/clusterio/pull/570).
+
+### Changes
+
+- Fixed Inventory Sync reporting a negative database size [#598](https://github.com/clusterio/clusterio/pull/598).
+- Fixed plugin events being invoked while a host connection was in an invalid state.
+- Suppresed bogus warning about event listener leak in the browser's console [#600](https://github.com/clusterio/clusterio/pull/600).
+- Fixed installer breaking on Windows after Node.js released a security fix [#614](https://github.com/clusterio/clusterio/pull/614).
+- During a data export the mod settings in mod packs will now be corrected to the type of the settings prototype if the type is incorrect.
+- Fixed missing color setting causing the Mod Pack view in the Web UI to show an error [#609](https://github.com/clusterio/clusterio/issues/609).
+
+Many thanks to the following for contributing to this release:  
+[@Cooldude2606](https://github.com/Cooldude2606)
+[@Danielv123](https://github.com/Danielv123)
+[@Hornwitser](https://github.com/Hornwitser)
+
+
 ## Version 2.0.0-alpha.17

 ### Features
@@ -90,13 +90,13 @@ Check out the documentation on [Writing Plugins](/docs/writing-plugins.md) for w

 ## Installation

-Clusterio runs on Node.js v18 and up, it's distributed via npm and comes with a guided install script.
+Clusterio runs on all LTS version of NodeJS, it is distributed via npm and comes with a guided install script.
 If you already have a recent Node.js installed, you can set it up in a new directory with:

    npm init "@clusterio"

-Otherwise see below for OS specific instructions.
-
+Otherwise see below for OS specific instructions.  
+Check out all our of decisions for [node, factorio, and operation support](/docs/decisions.md#supportability).

 ### Ubuntu setup

@@ -198,7 +198,7 @@ For the standalone installation mode you can use
 If you plan to make your cluster available externally set the address
 that it will be accessible under with, for example

-    npx clusteriocontroller config set controller.external_address http://203.0.113.4:1234/
+    npx clusteriocontroller config set controller.public_url http://203.0.113.4:1234/

 Change the url to reflect the IP, protocol, and port the controller is accessible under, dns names are also supported.
 If 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.
@@ -209,12 +209,17 @@ See the [readme for @clusterio/controller](/packages/controller/README.md) for m

 ## Managing Factorio mods

-Clusterio currently only provides a manual method for running mods on servers by copying them either to each instance's individual `mods` folder, or by copying them into a host installation's `sharedMods` folder which will link/copy them to the `mods` folder of each instance on that host if the file doesn't already exist in the `mods` folder for that instance.
-Mods are copied from `sharedMods` on Windows and symlinked on Linux, this means that when mods are removed from `sharedMods` the mods will also be removed from the instance's `mods` folder on Linux if it got there by being linked by Clusterio, but not on Windows.
+Mods 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 -> Factorio -> Mod pack. You can also set a default modpack for new instances in the controller settings.

-For managing the mod settings, the `mod-settings.dat` and `mod-list.json` files will also be linked/copied over if present in `sharedMods`, but since Factorio creates these files automatically it might be necessary to delete them from each instance's `mods` folder for changes to them in `sharedMods` to take effect.
+![Select mod pack for instance](docs/assets/config_select_mod_pack.png)

-Better remote management of mods is a planned feature.
+Mod 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 -> Export data.
+
+![Export mod configuration data](docs/assets/export_mod_config_data.png)
+
+Once this is done, the mod settings will show up under the modpack configuration page.
+
+![Mod settings configuration in web interface](docs/assets/mod_settings_configuration.png)


 ## Setting up shared storage
@@ -227,11 +232,11 @@ Do not install the [Clusterio mod](https://mods.factorio.com/mod/clusterio), thi

 ## Running Clusterio

-After completing the installation start up the controller and at least one host separately.
+After completing the installation and creating your admin user, start up the controller and at least one host separately.
 The installer provides the `run-controller` and `run-host` scripts to make this simple.
 Once 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.

-The 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.
+The 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.

 ### Running via Systemd

@@ -0,0 +1,119 @@
+/**
+ * Clean the repository of build and execution artifacts.
+ *
+ * clean: A quick clean that removes all build artifacts making the output safe to publish
+ * clean-tests: Removes all build and test artifacts should not be required if tests are setup correctly.
+ * clean-all: Removes all build, test, and execution artifacts. Including cluster config and logs!
+ */
+
+"use strict";
+const path = require("path");
+const fs = require("fs-extra");
+const yargs = require("yargs");
+
+const npmPackage = require("./package.json");
+const workspaces = npmPackage.workspaces
+	.map(p => p.slice(0, -2))
+	.filter(p => !p.includes("external_plugins"));
+
+let DRY = false;
+
+/**
+ * Attempt to remove a file / directory if it exists.
+ *
+ * @param {string} filePath The path to remove.
+ */
+async function tryRemove(filePath) {
+	if (await fs.exists(filePath)) {
+		// eslint-disable-next-line no-console
+		console.log(filePath);
+	}
+
+	if (!DRY) {
+		await fs.remove(filePath);
+	}
+}
+
+/**
+ * Removes all build artifacts
+ */
+async function removeBuildArtifacts() {
+	const tasks = [];
+
+	for (const workspace of workspaces) {
+		const basePath = path.resolve(workspace);
+		const packages = await fs.readdir(basePath);
+		for (const packageName of packages) {
+			tasks.push(
+				tryRemove(path.join(basePath, packageName, "dist"))
+			);
+			tasks.push(
+				tryRemove(path.join(basePath, packageName, "node_modules", ".cache"))
+			);
+		}
+	}
+
+	await Promise.all(tasks);
+}
+
+/**
+ * Removes all test artifacts
+ */
+async function removeTestArtifacts() {
+	const artifacts = [
+		".nyc_output", "coverage", "temp", "static",
+	];
+
+	await Promise.all(artifacts.map(artifact => tryRemove(path.resolve(artifact))));
+}
+
+/**
+ * Removes all execution artifacts
+ */
+async function removeExecutionArtifacts() {
+	const artifacts = [
+		"database", "instances", "logs", "mods",
+		"config-control.json", "config-controller.json", "config-host.json",
+		"FactorioAdminToken.txt", "plugin-list.json",
+	];
+
+	await Promise.all(artifacts.map(artifact => tryRemove(path.resolve(artifact))));
+}
+
+/**
+ * Main function for this script
+ */
+async function main() {
+	await yargs(process.argv.slice(2))
+		.scriptName("clean")
+		.option("dry-run", {
+			alias: "dry",
+			nargs: 0,
+			describe: "Will not delete any files",
+			default: false,
+			type: "boolean",
+		})
+		.command("all", "Remove all artifacts", () => {}, argv => {
+			DRY = argv.dry;
+			removeBuildArtifacts();
+			removeTestArtifacts();
+			removeExecutionArtifacts();
+		})
+		.command("tests", "Remove all build and test artifacts", () => {}, argv => {
+			DRY = argv.dry;
+			removeBuildArtifacts();
+			removeTestArtifacts();
+		})
+		.command("$0", "Remove all build artifacts", () => {}, argv => {
+			DRY = argv.dry;
+			removeBuildArtifacts();
+		})
+		.demandCommand(1, "A command must be specified")
+		.strict()
+		.parse();
+}
+
+// Run main if started from command line
+if (module === require.main) {
+	main();
+}
@@ -0,0 +1,6 @@
+coverage:
+  status:
+    project:
+      default:
+        if_ci_failed: success
+        informational: true
@@ -30,7 +30,7 @@ There's also the virtual connector which lets two links in the same program be c
 ## Message

 There's two types of messages currently implemented apart from the Link builtin close message and that's Request and Event.
-The builtin messages are defined in [packages/lib/link/messages.js](/packages/lib/link/messages.js) and are attached to links via the attachAllMessages function, which is usally called in the Link subclass constructor.
+The builtin messages are defined in [packages/lib/src/link/messages.ts](/packages/lib/src/link/messages.ts) and are attached to links via the attachAllMessages function, which is usally called in the Link subclass constructor.

 The messages define which links they are valid on and only attaches handlers for those links.
 There's also a forwarding mechanism for when a request or event is to be forwarded another hop.
@@ -6,7 +6,7 @@ Clusterio uses a field based configuration system to manage settings for the con
 Plugins can add their own config fields for the controller and instances configs.
 The fields are defined early in the startup, and fields for disabled plugins will still be created.

-The built-in config fields are defined in [packages/lib/config/definitions.js](/packages/lib/config/definitions.js) while plugins can add their own config field definitions to the `controllerConfigFields` and `instanceConfigFields` properties of the `plugin` export.
+The built-in config fields are defined in [packages/lib/src/config/definitions.ts](/packages/lib/src/config/definitions.ts) while plugins can add their own config field definitions to the `controllerConfigFields` and `instanceConfigFields` properties of the `plugin` export.
 A `<plugin_name>.load_plugin` field is automatically created for each plugin and it's used to enable/disable the loading plugins on startup.


@@ -51,9 +51,9 @@ interfaces.
 Defaults to null.


-### controller.external_address
+### controller.public_url

-External address the controller is accessible on.
+Public address the controller is accessible on.
 Currently only used for `clusteriocontroller bootstrap create-ctl-config` in order to give the right url to connect to.
 This should be a full URL ending with a /.

@@ -182,14 +182,6 @@ You can generate an access token with `clusterioctl host generate-token --id <ho
 Defaults to "enter token here".


-### host.tls_ca
-
-Path to certificate in PEM format to use for validating a TLS connection to the controller.
-If you have a self signed certificate on the controller you will need to copy the certificate to your hosts and set it as the certificate authority with this option.
-
-Defaults to null meaning use Node.js's default set of trusted certificate authorities.
-
-
 ### host.public_address

 External address instances hosted on this host can be accessed on.
@@ -239,6 +231,14 @@ Does not affect start or stop of the instance while the host is running.
 Defaults to false.


+### instance.exclude_from_start_all
+
+If enabled this instance will be excluded from the "Start all" button operation in the web interface.
+This allows you to prevent certain instances from being started when using the bulk start operation.
+
+Defaults to false.
+
+
 ### factorio.version

 Version of Factorio to use for this instance.
@@ -405,14 +405,6 @@ You can generate an access token with `clusteriocontroller bootstrap generate-us
 Defaults to null meaning complain about it not being set and exit.


-### control.tls_ca
-
-Path to certificate in PEM format to use for validating a TLS connection to the controller.
-If you have a self signed certificate on the controller you will need to copy the certificate to the computer you run clusterctl from and set it as the certificate authority with this option.
-
-Defaults to null meaning use Node.js's default set of trusted certificate authorities.
-
-
 ### control.max_reconnect_delay

 Max duration in seconds to wait before attempting to reconnect with the controller after the connection is dropped.
@@ -3,6 +3,8 @@
 You are probably reading this because you want to contribute code to Clusterio.
 Great!  We need people like you.
 Though we have some conventions and workflows that we kindly ask you to follow.
+We have included all the pratical considerations in this document.
+Although, we recomend checking out out our [past decisions](/docs/decisions.md) if you have the time.


 ## Contents
@@ -15,6 +17,7 @@ Though we have some conventions and workflows that we kindly ask you to follow.
    - [Editing your Feature Branch](#editing-your-feature-branch)
    - [Resolving Merge Conflicts](#resolving-merge-conflicts)
    - [Updating Your GitHub Fork](#updating-your-github-fork)
+    - [Publishing releases to npm](#publishing-releases-to-npm)
 - [Changelog](#changelog)
 - [Supported Node.js and Factorio Version](#supported-node.js-and-factorio-version)
 - [Code Style](#code-style)
@@ -23,7 +26,6 @@ Though we have some conventions and workflows that we kindly ask you to follow.
    - [Indenting](#indenting)
    - [Line Length](#line-length)
    - [Markdown](#markdown)
- [Pushing releases to npm](#pushing-releases-to-npm)


 ## Workflow
@@ -178,11 +180,15 @@ Fetch the main repository directly as described above and base your feature bran
 GitHub has no interface or functionality for keeping the branches in your fork up to date with the branches in the main repository and there is no point in doing this for our feature branch based workflow.


+### Publishing releases to npm
+
+For publishing new releases see [package release workflow](./release-workflow.md#packages).
+
 ## Changelog

 There's a [Changelog](../CHANGELOG.md) in the root of the project.
 If you make changes that are visible to users of this project you should add an entry to the changelog describing what has changed.
-The format of this log should be self explanatory, please follow it carefully.
+The format of this log should be self explanatory, please follow it carefully. Please make sure to document any [breaking changes](/docs/decisions.md#breaking-changes).


 ## Supported Node.js and Factorio Versions
@@ -194,12 +200,14 @@ For Factorio Clusterio 2.0 aims to support version 0.17.69 and up, including the
 It's recommended that you use the lua API reference for 0.17.69, as there's no information on what version Factorio API's were introduced in.
 The GitHub Actions tests are run against the latest experimental release.

+Check out all our of decisions for [node, factorio, and operation support](/docs/decisions.md#supportability).
+

 ## Code Style

 The style of the code is a bit of a mixed bag at the moment.
 But there are at least a few things that have been agreed upon.
-
+See our [decisions document](/docs/decisions.md) for justifcations.

 ### Naming style

@@ -284,41 +292,3 @@ And there's two spaces before the next heading.

 Headings use the `# heading` format.
 ```
-
-
-## Pushing releases to npm
-
-The releases are done by updating packages versions and then publishing them with pnpm.
-You will need commit access to the repository as well publish access to the @clusterio org on npm to do this.
-
-1.  To do a release switch to the master branch and make sure it's up to date with the repository before proceeding.
-
-    ```sh
-    git switch master
-    git pull --ff-only upstream master
-    ```
-
-    Check and make sure there are no untracked files with `git status`.
-
-2.  Update the version in package files.
-    Make sure to update the command for the right version jump.
-
-    ```sh
-    sed -i 's/2\.0\.0-alpha\.12/2\.0\.0-alpha\.13/' {packages,plugins}/*/package.json
-    ```
-
-3.  Inspect, commit and tag the changes.
-    Again, make sure to be tagging the right version.
-
-    ```sh
-    git add -p
-    git commit -m v2.0.0-alpha.13
-    git tag v2.0.0-alpha.13
-    ```
-
-4.  Publish the packages.
-
-    ```sh
-    rm -r ./{plugins,packages}/*/dist
-    pnpm -r --filter='./{plugins,packages}/*' publish
-    ```
@@ -0,0 +1,479 @@
+# Decisions
+
+This document outlines key decisions taken by the project team that should be followed by all maintainers and contributors.
+If there is a particular issue or concern you would like the team to comment on then please create a github issue for it.
+
+<!-- Try to use categories that already exist if possible -->
+<!-- Sublists should be alphabetical, avoiding starting with "the" -->
+<!-- For code style, add (Lang) to section names if present in both -->
+
+1. Documentation
+    - [Decision Log](#decision-log)
+    - [TSDoc](#tsdoc)
+2. Code Style (General)
+    - [Indenting](#indenting)
+    - [Line Length](#line-length)
+    - [Naming Booleans](#naming-booleans)
+    - [Naming Files](#naming-files)
+    - [Naming Times and Durations](#naming-times-and-durations)
+    - [Strings](#strings)
+3. Code Style (TS / JS / Web)
+    - [ESLint](#eslint)
+    - [Imports Within `lib` Package](#imports-within-lib-package)
+    - [Name Style](#name-style-ts)
+4. Code Style (Lua)
+    - [FMTK](#fmtk)
+    - [Name Style](#name-style-lua)
+5. Code Style (Other)
+    - [Markdown](#markdown)
+6. Repository Structure
+    - [External Plugins](#external-plugins)
+    - [First Party Plugins](#first-party-plugins)
+    - [Core Packages](#core-packages)
+    - [TypeScript Configs](#typescript-configs)
+    - [Workspace](#workspace)
+7. Project Architecture
+    - [Deprecation of Phin in favour of `fetch`](#deprecation-of-phin-in-favour-of-fetch)
+    - [Minimal Dependencies](#minimal-dependencies)
+    - [React](#react)
+    - [Separation of Host and Controller](#separation-of-host-and-controller)
+    - [Typescript](#typescript)
+    - [Webpack](#webpack)
+8. Supportability
+    - [Breaking Changes](#breaking-changes)
+    - [Distribution](#distribution)
+    - [Factorio](#factorio)
+    - [General Support](#general-support)
+    - [NodeJS](#nodejs)
+    - [Operating System](#operating-systems)
+9. Testing
+    - [Continuous Integration](#continuous-integration)
+    - [Continuous Deployment](#continuous-deployment)
+    - [Mocha](#mocha)
+    - [Version Matrix](#version-matrix)
+
+> [!note]
+> The use of `Time Immemorial` indicates an obsverion of a previously undocumented decision with no known start date, which has remained unchallenged.
+
+<!--
+### Template
+
+🧾 0th Month 2000 | Source
+
+> A short sentence describing the action to take in the context of our project.
+
+Write a breif description which includes: the reason a decision was needed, the outcome of the discussion, and the justification of the outcome.
+Write using the active voice in third person "we".
+Remember to have one sentence per line.
+-->
+
+
+## Documentation
+
+### Decision Log
+
+🧾 22nd December 2024 | Discord Voice Call
+
+> Maintain a document that includes a brief description of the outcomes and the reasoning behind our decisions, along with links to the relevant sources for further reading.
+
+We discovered that we were beginning to ask similar questions to other maintainers that we had previously raised, which led to a waste of time for all involved.
+Consequently, we decided that a log of important decisions should be kept for the benefit of ourselves and future maintainers.
+
+
+### TSDoc
+
+🧾 12th August 2023 | [Discord Discussion](https://discord.com/channels/450361298220351489/450361298220351491/1320573126731370506) | [Github PR #493](https://github.com/clusterio/clusterio/pull/493)
+
+> When a function or it's arguments do not have a clear purpose, a TSDoc comment should be used to describe it.
+
+While TypeScript provides useful type infomation in function hover text, it does not allow for comments about the purpose of functions and their arguments.
+Therefore, we decided to use TSDoc comments for this purpose as it is well intergrated in many text editors and IDEs (such as VSCode).
+Our specific implementation is TypeDoc because it is lightweight it and can output TSDoc comments as html.
+API Extractor was also considered but not selected.
+
+
+## Code Style (General)
+
+### Indenting
+
+🧾 Time Immemorial  
+
+> Use tabs for indention. Except for Markdown where spaces carry meaning.
+
+We needed to maintain a consistent whitespace style across all our files.
+Therefore, we selected tabs as our standard.
+
+
+### Line Length
+
+🧾 Time Immemorial  
+
+> Lines are limited to 120 characters where tabs count as 4 characters.
+
+We needed to maintain a consistent max line legnth across all our files.
+Therefore, we selected 120 characters as our standard.
+
+
+### Naming Booleans
+
+🧾 25th November 2024 | [Discord Discussion](https://discord.com/channels/450361298220351489/450361298220351491/1310611960508977223)
+
+> Variable and member properties which contain booleans should be named starting with a verb unless it ends with "ed", e.g. `canRestart` `expectEmpty` `hasFallback` `connected` `enabled` `loaded` `banned`
+
+We had inconsistencies in our naming of booleans and aimed to standardise them.
+There was little preference for any particular approach, so we chose the one that would require the fewest changes to existing code.
+As a result, all boolean values should begin with a verb, unless they end with "ed." For clarity, both "is" and "has" are considered verbs.
+
+
+### Naming Files
+
+🧾 Time Immemorial  
+
+> Files use lowercase_underscore if multiple values are exported. If a single class is exported then it uses the class name in PascalCase.
+
+We needed to maintain a consistent name style across all our files.
+Therefore, we selected lowercase undercore for most files, with class files using PascalCase.
+
+
+### Naming Times and Durations
+
+🧾 18th January 2024 | [Discord Discussion](https://discord.com/channels/450361298220351489/450361298220351491/1197566542548828170)
+
+> Variable and member properties which contain times or durations should end with their SI unit of messure, e.g. `updatedAtMs`
+
+We found verifying the units of measurement used in different locations to be a simple yet repetitive task that could lead to errors.
+Our main concern was the mixing of variables containing seconds and milliseconds.
+Therefore, we decided that times and durations should explicitly include their units, whereas other value types do not require any units.
+
+
+### Strings
+
+🧾 Time Immemorial  
+
+> Strings should use double quotes `"` unless the string contains them, in which case single quotes `'` can be used. For JS string templates use backticks ``` ` ``` as normal.
+
+We needed to maintain a consistent string style across all our files.
+Therefore, we selected double quotes as our standard.
+
+## Code Style (TS / JS / Web)
+
+### ESLint
+
+🧾 Time Immemorial  
+
+> Use ESLint for style checking.
+
+We needed to maintain a consistent style across all our files.
+Therefore, we utilise the industry-standard ESLint, as it is familiar and highly configurable.
+
+
+### Imports Within `lib` Package
+
+🧾 Time Immemorial  
+
+> When importing files within the lib package, all names should be prefixed with "lib".
+
+The exports of the various library files are often very generic and may conflict with variable names.
+Therefore, when importing these files the "lib" prefix should be used to avoid confussing.
+This only applies to files within `lib` importing other files in `lib` because all other packages import the whole of `lib` as a single package.
+
+
+### Name Style (TS)
+
+🧾 Time Immemorial  
+
+> Variables and members of classes use camelCase. Classes use PascalCase. Config values use lowercase_underscore. Exceptions allowed for over the write objects.
+
+We needed to maintain a consistent name style across all our files.
+Therefore, we follow common practive for JavaScript of using camelCase and PascalCase.
+Although, we have also allowed the use of lowercase_underscore for config values to distinguish them from other variables.
+
+
+## Code Style (Lua)
+
+### FMTK
+
+🧾 14th June 2024 | [External PR](https://github.com/justarandomgeek/vscode-factoriomod-debug/pull/126)
+
+> Use of FMTK is not required but is advised.
+> To enable Clusterio support, use the CLI flag `--clusterio-modules` under `Lua.runtime.pluginArgs`.
+
+We needed to maintain a consistent style across all our files.
+There are multiple competing standards for Lua code, and given the limited amount of Lua code in this project, we chose not to adopt any automatic linting or shared luarc file.
+Nevertheless, we recomend the use of [FMTK](https://github.com/justarandomgeek/vscode-factoriomod-debug) and have taken steps towords supporting it in Clusterio.
+
+
+### Name Style (Lua)
+
+🧾 Time Immemorial  
+
+> Everything uses lowercase_underscore
+
+We needed to maintain a consistent name style across all our files.
+Therefore, we follow common practive for Lua of using lowercase_underscore.
+
+
+## Code Style (Other)
+
+### Markdown
+
+🧾 Time Immemorial  
+
+> Use one sentence per line.
+> Place two lines before each heading, except for the first one or when two headings are adjacent.
+
+We needed to maintain a consistent code style across all our markdown files.
+Therefore, we selected an approach which makes diff reports more useful and which makes headings use additional space to make them stand out.
+
+
+## Repository Structure
+
+### External Plugins
+
+🧾 Time Immemorial
+
+> No external plugins should be included in the main repository.
+> A folder will exist which external plugin repositories can be cloned into and will be given the same treatment as first party plugins.
+
+We require a designated space for developers to create their plugins without the concern of conflicts with first-party plugins.
+To address this, we have introduced a dedicated folder for external plugins.
+This solution is straightforward and has since proven to be highly effective.
+
+
+### First Party Plugins
+
+🧾 Time Immemorial
+
+> First party plugins are included in the main repository.
+> Those selected to be first party are held to the same stanards which apply to the core packages.
+> Each will recieve a new release in step with the core packages.
+
+We require a designated space for first-party plugins, separate from the core packages, to clearly represent the dependency between them.
+Creating a folder provided a simple solution to this.
+
+
+### Core Packages
+
+🧾 Time Immemorial
+
+> All core packages will be contained in the packages folder of the repository.
+> They are allowed to be interdependent on each other.
+
+We require a set of core packages to represent the different applications used in a cluster.
+See [Separation of Host and Controller](#separation-of-host-and-controller).
+To avoid putting more files into the repository root we created a folder for the core packages.
+
+
+### TypeScript Configs
+
+🧾 26th August 2023 | [Github PR #504](https://github.com/clusterio/clusterio/pull/504)
+
+> Each package / plugin may contain any of: `tsconfig.json` `tsconfig.node.json` and `tsconfig.web.json`.
+> The main respository root will contain all three files in addition to `tsconfig.base.json` which node and web extend from.
+> The configs inside packages / plugins should extend from those in the respository root.
+
+We found that maintaining independent tsconfig files became burdensome and required a way to consolidate them.
+Initially, we introduced a base configuration file; however, this proved insufficient, so we extended it to include separate configurations for Node.js and the Web.
+This approach led to each package having up to three tsconfig files.
+Nevertheless, we believe this to be justified, given the need to differentiate between Node.js and Web builds while maintaining a single, shared configuration.
+
+
+### Workspace
+
+🧾 Time Immemorial
+
+> The workspace root should contain only: configuration files, scripts used to build / clean the workspace, the readme, and the changelog.
+
+We need to maintain a clean workspace root by only including files which effect all pacakges and plugins such as configuration files.
+We have allowed for build and clean scripts to exist here as long as they are not published as part of any package or plugin.
+
+
+## Project Architecture
+
+### Deprecation of Phin in favour of `fetch`
+
+🧾 12th December 2024 | [Discord Discussion Dec 24](https://discord.com/channels/450361298220351489/450361298220351491/1316781609206419567) | [Discord Discussion May 25](https://discord.com/channels/450361298220351489/450361298220351491/1240246997496102942)
+
+> The builtin `fetch` method should be used as a replacement of the deprecated Phin module.
+
+We required a replacement for the deprecated Phin HTTP client, which was used for making server-side requests and as part of testing.
+With `fetch` being marked as stable in Node.js v21.0.0 and having first been made available in v16.15.0, it serves as a suitable replacement without the need to add new dependencies.
+It had previously not been used because it was not marked as stable in any LTS version of NodeJS.
+
+
+### Minimal Dependencies
+
+🧾 Time Immemorial
+
+> Any new dependencies need to be well justified.
+
+We aim to minimise our exposure to upstream changes by using a minimal number of dependencies.
+This also serves to reduce the bloat of a cluster installation and improve installation times.
+Consequently, the addition of any new dependencies must be thoroughly justified, with evidence of research into alternative options and comparisons between them.
+
+
+### React
+
+🧾 Time Immemorial
+
+> Our web stack uses ReactJS
+
+We require a reactive website for our control panel, and ReactJS was selected due to its widespread use and familiarity.
+Switching away from React for any reason would represent a significant undertaking.
+
+
+### Separation of Host and Controller
+
+🧾 Time Immemorial
+
+> The primary application locations are Control (web and cli), Controller, and Host.
+> Therefore the core packages are: `ctl` `controller` `host`. There are two libaray packages `lib` and `web_ui`.
+> Additionally `create` exists to provide easy creation of a cluster.
+
+A single application to perform all the duties of a cluster would complicate the reasoning and maintenance of the project, so we decided to split it into several packages.
+The primary components of a cluster include servers connected to an instance, which runs on a host that connects to the controller, whose configuration is managed via a control connection from a CLI or web portal.
+Based on this structure, we found it logical to divide the packages according to their installation location, resulting in `ctl`, `controller`, and `host`, with shared code separated into `lib` and `web_ui` depending on where it is utilised.
+The additional `create` package is used by `npm create` to provide a user-friendly installation process.
+
+
+### TypeScript
+
+🧾 6th August 2023 | [Github PR #491](https://github.com/clusterio/clusterio/issues/491)
+
+> We use TypeScript as our language of choice.
+
+We previously used JavaScript and switched to TypeScript to provide a robust type system.
+Transitioning to any other langauge would be too significant an undertaking.
+Initially, we supported multiple languages for plugins, including Rust and Go; however, this approach was quickly abandoned due to its complexity.
+
+
+### Webpack
+
+🧾 Time Immemorial
+
+> Our web stack uses Webpack and associated plugins.
+
+We required a bundler for our web build, and at the time, Webpack was the standard.
+While we have considered alternatives since, transitioning to another solution would be a significant undertaking.
+
+
+## Supportability
+
+### Breaking Changes
+
+🧾 Time Immemorial
+
+> We follow symver versioning for breaking changes.
+> In our alpha stage, we allow every alpha to contain breaking changes as long as their are documented and provide migration actions.
+> Once we enter beta, breaking changes will be more restricted.
+
+We aim to be highly transparent with breaking changes and maintain compatibility with as many existing installations as possible.
+However, as we are currently in the alpha stage, things are unstable, and breaking changes occur frequently.
+As such, we have decided to document all breaking changes and provide migration steps where the changes are non-trivial.
+Once we enter the beta stage, we will implement stricter restrictions on breaking changes.
+
+
+### Distribution
+
+🧾 Time Immemorial
+
+> We use `git` and `pnpm` for development distribution.
+> We use `npm` and the factorio mod portal for production distribution.
+
+We need to distribute both production builds and development source code for the project.
+By necessity, we use `npm` and the Factorio Mod Portal to distribute our production builds.
+For development, we rely on `git` and GitHub, which are industry standards, while using `pnpm` as a more efficient variant of `npm` for development installations.
+Although bun was considered upon its release, we were not convinced it was the right choice.
+
+
+### Factorio
+
+🧾 26th October 2024 | [Discord Discussion](https://discord.com/channels/450361298220351489/450361298220351491/1299637042350653461)
+
+> We actively provide full support for the last two major versions of Factorio.
+> This approach does not follow semantic versioning; instead, it follows the "middle" versions: 2.1 > 2.0 > 1.1 > 1.0 > 0.18 > 0.17.
+> We offer passive support for all versions from 0.17 onwards, where implementation is trivial and does not impose restrictions on our actively supported versions.
+
+Following the 2.0 update of Factorio, which introduced a large number of breaking changes, we needed to reconsider which versions would be actively supported, as it was no longer trivial to support all versions.
+Anticipating that future breaking changes would also be significant, and assuming the majority of players would update to the latest stable version upon release, we decided to support the latest stable version and the previous major version that introduced breaking changes.
+Support for other versions will not be removed if they have already been implemented and do not impose restrictions on our ability to support newer versions.
+
+
+### General Support
+
+🧾 Time Immemorial
+
+> We provide full support via GitHub and our Discord server for the latest published version of Clusterio, as well as assistance with migrating from the previous published version.
+> However, we do not offer any guarantees with our support; we assist when time permits and may not be able to resolve every issue.
+> Additionally, while we offer support in setting up development workspaces and guidance for plugin development, we do not provide support for those running development builds as production instances.
+
+We aim to support as many users of Clusterio as possible in setting up and using the platform for a variety of purposes, including setting up production instances, development workspaces, and providing guidance on plugin development.
+However, our time to work on Clusterio is limited, and even more so our ability to offer support.
+As such, we cannot assist with every issue and must set reasonable restrictions to ensure expectations are aligned.
+Consequently, we do not offer any guarantees for our support, but we strive to provide as much assistance as possible for those setting up or running the latest published version.
+Additionally, we support users in setting up development workspaces, as the more people willing to contribute, the better.
+
+
+### NodeJS
+
+🧾 Time Immemorial
+
+> We support all LTS versions of NodeJS in their active and maintenance phases.
+
+Our options were: supporting all versions, supporting all active versions, supporting all LTS versions, or supporting only the latest version.
+As we aim to provide a stable, production-ready tool while still limiting the number of versions we need to manage, we chose to support all LTS versions because NodeJS can be installed by the majority of linux distro package managers which will always offer at least one LTS version.
+
+
+### Operating Systems
+
+🧾 Time Immemorial
+
+> We support all major versions of Windows, Linux, and MacOS.
+This is largely inpart to our use of NodeJS and is not a guarantee from us.
+
+Our choice of Node.js has enabled us to support all major operating systems with minimal effort on our part.
+Nevertheless, there have been instances where code paths have diverged between systems, and we have attempted to maintain support for as many systems as possible.
+However, this is not a priority, and such support has often been reactive or provided by external contributors.
+
+
+## Testing
+
+### Continuous Integration
+
+🧾 Time Immemorial
+
+> We run unit and integration tests through GitHub CI actions as well as test coverage through CodeCov.
+
+Continuous integration actions in GitHub are a valuable tool that we use to assist with the review of pull requests from both maintainers and contributors.
+While we aim to increase the number of useful checks performed by CI in the future, this is not a priority over the development of new features.
+
+
+### Continuous Deployment
+
+🧾 Time Immemorial
+
+> We do not use any CD actions, and have no plans of implementing them.
+
+Unlike CI, we do not find continuous deployment useful at our current stage of the project.
+This is due to the frequent breaking changes merged into the main branch, which we prefer to bundle together as a single version.
+In the future, we may automate the deployment process, but it will always require manual activation.
+
+
+### Mocha
+
+🧾 Time Immemorial
+
+> We use Mocha for testing and CodeCov for coverage.
+
+We chose Mocha because it was a good fit when we selected it.
+However, we are always looking for a better framework which is worth the effort of switching.
+
+
+### Version Matrix
+
+🧾 Time Immemorial
+
+> We perform all tests through GitHub actions using Ubuntu latest, using all supported versions of node and all supported versions of factorio.
+
+We perform tests on all versions of NodeJS and Factorio that we support.
+However, we do not conduct tests on all supported operating systems, as the added demand on our testing resources would be significant, and the value it would provide for a cross-platform engine like NodeJS would be limited.
@@ -120,7 +120,7 @@ There's also the `add_libraries` function exported by event_handler, which accep
 ## Communicating with Clusterio

 Clusterio uses a homebrew protocol based on sending JSON payloads over a WebSocket connection.
-See [socket.md](socket.md) for the implementation details of it.
+See [protocol.md](devs/protocol.md) for the implementation details of it.

 It's also possible to write a plugin for Clusterio that exposes a custom interface over HTTP, WebSocket or any other technology supported by Node.js.

@@ -1,7 +1,7 @@
 # Protocol

 Clusterio communicates using a simple homebrew message passing protocol based on JSON over WebSocket with limited support for reliable transport of messages.
-The protocol is implemented in [packages/lib/link](/packages/lib/link) and uses the `ws` library to handle the WebSocket connections on the Node.js side and the native WebSocket API on the browser side.
+The protocol is implemented in [packages/lib/src/link](/packages/lib/src/link) and uses the `ws` library to handle the WebSocket connections on the Node.js side and the native WebSocket API on the browser side.

 Two general kinds of messages are supported: events and requests.
 Events are messages sent by one party and received by the other and offer no notification for the sender on whether it was actually received.
@@ -166,7 +166,7 @@ Events are messages send in one direction over the link, that the receiver is ex
 By convention message types ending in `*_event` are events.
 The data payload of an event consists solely of event specific properties.

-See [packages/lib/link/messages.js](/packages/lib/link/messages.js) for the recognized core events and their contents.
+See [packages/lib/src/link/messages.ts](/packages/lib/src/link/messages.ts) for the recognized core events and their contents.
 Plugins may defined their own events as well.

 #### `*_event`
@@ -181,7 +181,7 @@ They function a lot like HTTP requests except that both parties of a connection
 By convention message types ending in `*_request` are requests, and is expected to be replied to with a corresponding `*_response` message.
 If an error occured while processing the request an error response containing an error property in the data payload is sent instead.

-See [packages/lib/link/messages.js](/packages/lib/link/messages.js) for the recognized core requests and their contents.
+See [packages/lib/src/link/messages.ts](/packages/lib/src/link/messages.ts) for the recognized core requests and their contents.
 Plugins may define their own requests as well.

 #### `*_request`
@@ -28,6 +28,21 @@ Generate a token for a host. `--id` is the host id.

 Create a host config. `--id` id the host id. `--name` is the host name. `--generate-token` decides whether to also generate a token, defaulting to `0`. `--output` is the filename for the output of the config; Default is "config-host.json", "-" for stdout.

+### Update Clusterio
+
+    ctl> host update [--id <host id>] [--name <host name>] [--restart]
+
+If remote updates are enabled on the host, this will attempt to update `@clusterio/host` on the machine. 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 [--restart]
+    controller> config set controller.allow_remote_updates true/false
+
 ## Instances

 ### List Instances
@@ -199,3 +214,50 @@ Note: If the player joins the cluster again a new account will be made for them
 ## Roles

 To be written.
+
+
+## Plugins (Local)
+
+To be written.
+
+
+## Plugins (Remote)
+
+By default, remote updates are enabled unless you selected "no" during installation.
+Remote updates allow ctl and the web UI to update plugins on machines within the cluster.
+However, remote installations are disabled by default to prevent the risk of arbitrary code execution through the installation of malicious npm packages onto the machine. See below if you wish to enable this feature.
+
+### 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> [--restart]
+    ctl> host plugin update <host> <name> [--restart]
+
+If remote plugin updates are enabled on the remote, this will execute `npm update --save <name>`. 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.
+
+### Install
+
+    ctl> controller plugin install <name> [--restart]
+    ctl> host plugin install <host> <name> [--restart]
+
+If remote plugin installs are enabled on the remote, this will execute `npm install --save <name>`. 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.
+
+### 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.
@@ -10,6 +10,10 @@ You can do this by running the follow RCON command on an instance that is curren

    /sc local m={name="pack",description="",factorio_version=game.active_mods.base,mods={},settings={startup={},["runtime-global"]={},["runtime-per-user"]={}}} for n,v in pairs(game.active_mods) do table.insert(m.mods,{name=n,enabled=true,version=v}) end local function set(s,c) for n,v in pairs(s) do m.settings[c][n]=v end end set(settings.startup,"startup") set(settings.global,"runtime-global") if game.player then set(game.player.mod_settings,"runtime-per-user") else set(settings.player,"runtime-per-user") end local e=game.encode_string(game.table_to_json(m)) log(e) rcon.print(e)

+If you for some reason want to run this function in 2.0+, use the following command:
+
+    /sc local a={name="pack",description="",factorio_version=script.active_mods.base,mods={},settings={startup={},["runtime-global"]={},["runtime-per-user"]={}}}for b,c in pairs(script.active_mods)do table.insert(a.mods,{name=b,enabled=true,version=c})end;local function d(e,f)for b,c in pairs(e)do a.settings[f][b]=c end end;d(settings.startup,"startup")d(settings.global,"runtime-global")if game.player then d(game.player.mod_settings,"runtime-per-user")else d(settings.player,"runtime-per-user")end;local g=helpers.encode_string(helpers.table_to_json(a))log(g)rcon.print(g)
+
 This should produce a [Mod Pack String](https://forums.factorio.com/viewtopic.php?f=96&t=103578) which you need to copy and paste somewhere to keep it for later.
 Mod Pack strings looks something like this:

@@ -0,0 +1,67 @@
+# Release workflow
+
+## Update changelog
+
+- CHANGELOG.md in the repository root
+- The changelog.txt file in mod directories
+
+Pull requests will usually have suggestions for changelog entries.
+
+## Packages
+
+> [!NOTE]
+> You will need commit access to the repository as well publish access to the @clusterio org on npm to do this.
+
+1. Ensure you are on the latest version of master branch with no untracked files
+
+    ```sh
+    git switch master
+    git pull --ff-only upstream master
+    git status
+    ```
+
+2. Bump the version in the `package.json` files
+
+    ```sh
+    sed -i 's/2\.0\.0-alpha\.XX/2\.0\.0-alpha\.YY/' {packages,plugins}/*/package.json
+    ````
+
+3. Tag and push the release to github
+
+    ```sh
+    git add -p
+    git commit -m v2.0.0-alpha.XX
+    git tag v2.0.0-alpha.XX
+    ```
+
+4. Perform a clean install and publish the packages.
+
+    ```sh
+    pnpm clean
+    pnpm -r --filter='./{plugins,packages}/*' publish
+    ```
+
+## Plugins
+
+1. Bump the version in the `package.json` file
+2. Run `pnpm install` in the repository root
+3. Run `pnpm adduser` to authenticate
+4. Run `pnpm publish` in the plugin/package directory
+
+Before confirming the publish, ensure the packed size is approximately the same size as the last version (or within the expected size)
+
+After publishing, test creating and installing the plugin on a fresh install.
+
+## Lua mods
+
+To publish lua mods like clusterio_lib, start by building from source:
+
+```sh
+pnpm run build-mod
+```
+
+or download the latest artifacts from the CI. When uploading the mods to the mod portal, make sure the latest version is the last version uploaded, as the game/mod portal/ingame updater isn't consistent in how it figures out the "latest version"
+
+## Release notes
+
+Release notes are expected to be published alongside new releases. We use the github releases system as well as posting in the #announcements channel on the discord. Major releases may warrant a ping.
@@ -63,10 +63,25 @@ This creates a private key file named `key.pem` and a public certificate file na
    npx clusteriocontroller config set controller.tls_certificate cert.pem
    npx clusteriocontroller config set controller.tls_private_key key.pem

-Additionally you will need copy the `cert.pem` file to all of the computers you want to set up as hosts and configure it as the `host.tls_ca` option:
+Additionally you will need copy the `cert.pem` file to all of the computers you want to set up as hosts and configure node to trust it by setting the `NODE_EXTRA_CA_CERTS` environment variable to a path to this file before the host is started. You can do this by passing `--self-signed-cert path/to/cert` to the installer when setting up a host, or manually by editing run-host.cmd, run-host.sh and/or clusteriohost.service by adding the following line next to the one setting `NODE_OPTIONS`: 

-    npx clusteriohost config set host.tls_ca cert.pem
+**For run-host.cmd**

-You will also need to copy the `cert.pem` file to all of the computers you want to remotely manage the cluster via clusterctl and configure it as `control.tls_ca` option:
+    set "NODE_EXTRA_CA_CERTS=path\to\cert.pem"

-    npx clusterioctl control-config set control.tls_ca cert.pem
+**For run-host.sh**
+
+    export "NODE_EXTRA_CA_CERTS=path/to/cert.pem"
+
+**For clusteriohost.service**
+
+    Environment=NODE_EXTRA_CA_CERTS=path/to/cert.pem
+
+You will also need to copy the `cert.pem` file to all of the computers you want to remotely manage the cluster via clusterctl and set the `NODE_EXTRA_CA_CERTS` environment variable as a path to that file before running clusterioctl. For example:
+
+    # On Windows
+    set "NODE_EXTRA_CA_CERTS=path\to\cert.pem"
+    # On Linux
+    export NODE_EXTRA_CA_CERTS="path/to/cert.pem"
+    # You can now use clusterioctl
+    npx clusterioctl instance list
@@ -12,8 +12,6 @@ The plugin classes have pre-defined hooks that are called during various stages
 - [Plugin Configuration](#plugin-configuration)
 - [Communicating with Factorio](#communicating-with-factorio)
 - [Defining Link Messages](#defining-link-messages)
-    - [Defining Events](#defining-events)
-    - [Defining Requests](#defining-requests)
 - [Sending Link Messages](#sending-link-messages)
    - [Handling connection events](#handling-connection-events)
 - [Collecting Statistics](#collecting-statistics)
@@ -41,6 +39,7 @@ The usual guides for creating such packages apply.
 At minimum the `package.json` file must contain a version entry.

 A possible workflow for developing plugins is to place the plugin in a sub-directory of where clusterio has been installed, and rely on Node.js searching up the folder heirarchy for it to find `@clusterio/lib`.
+After creating a directory for your plugin, the boilerplate can be generated automaticlly from a set of tempaltes using `npm exec @clusterio/create -y -- --plugin-template` after which you will be asked which areas your plugin will interact with and your plugin's name.
 To add it to `plugin-list.json` so that it gets loaded use the `plugin add <path>` sub-command to either clusteriocontroller, clusteriohost or clusterioctl.
 Note that it's important that the path starts with ./ or ../ (use .\ or ..\ on Windows).

@@ -302,6 +301,20 @@ local clusterio_api = require("modules/clusterio/api")
 clusterio_api.send_json("my_plugin_foo", { data = 123 })
 ```

+For convience a helper function is exposed on server specifically for handling IPC events.
+
+```js
+async init() {
+    this.instance.server.handle("my_plugin_foo", this.handleFoo.bind(this));
+}
+
+async handleFoo(content) {
+    // Do stuff with content
+}
+```
+
+**Note:** This only handles IPC events, all other events must use `on`. You should not include the `ipc-` prefix when using this method. Error logging is handled for you, if you want custom error handling use `on`.
+
 It's recommended to either use the plugin name as the channel name or to prefix the channel name with the name of the plugin if you need multiple channels.
 It's also important to catch any errors that might occur as they will otherwise be propogated to the instance code and kill the server.

@@ -325,175 +338,137 @@ Events are simple one-way notifications that invoke a handler on the target it's
 Requests are pairs of request and response messages where the request is sent to the target and the response is the reply back from the target.
 The requests are similar to HTTP requests, except both parties of a link may initiate one.

-
-### Defining Events
-
-Events are defined as properties of the messages object exported on `plugin` that map to instances of the `Event` class from `lib/link`.
-The name of the property correspond to the handler invoked on the plugin class.
-The Event constructor takes an object of properties that define the event, for example the following could be defined in `plugin`:
-
-```js
-messages: {
-    startFrobnication: new lib.Event({
-        type: "foo_frobber:start_frobnication",
-        links: ["controller-host", "host-instance"],
-        forwardTo: "instance",
-        eventRequired: ["frobnication_type"],
-        eventProperties: {
-            "frobnication_type": { type: "string" },
-            "urgent": { type: "boolean" },
-        },
-    }),
-},
-```
-
-This specifies an event that can be sent from the controller to a host, and from a host to an instance.
-It also specifies that the event must contain the property `frobnication_type`, with a string value in the data payload and that it may optionally contain a boolean `urgent` property.
-It will also be forwarded by hosts to a specific instance.
-
-The following properties are recognized by the Event constructor:
-
-#### type
-
-The message type sent over the wire.
-This must start with the name of the plugin followed by colon and and be unique for the plugin.
-The type of the message sent over the socket will have the suffix `_event` appended to it.
-
-#### links
-
-An array of strings describing which links this event can be sent over.
-Direction matters, `"controller-host"` means the event can be sent from the controller to the host, but can't be sent back the other way, unless `"host-controller"` is also present in the links array.
-
-The available endpoints are `controller`, `host`, `instance`, and `control`.
-Controller talks with host and control, and host talks to instance.
-The full chain must be specified as the individual links in order for a message to travers multiple hops, (i.e., for a message to go from controller to instance it must have both `"controller-host"` and `"host-instance"` in the links array).
-See `forwardTo` and `broadcastTo` for ways to forward an event to the next link in a chain.
-
-#### forwardTo
-
-Target to forward an event to.
-Can either be `"controller"`, to indicate a host should forward it to the controller, or `"instance"`, to indicate it should be forwarded to the instances specified by the `instance_id` event property.
-This works by using a default handler for the event at the links that forward it.
-
-#### broadcastTo
-
-Target to broadcast this message towards.
-A value of "instance" means the event will be broadcast to all instances downstream of the target it's sent to, but not back from where it came from.
-Currently, only "instance" is supported.
-This means that sending the event to a host from an instance will cause it to be broadcast to all instances of that host except for the instance it came from.
-
-#### eventRequired
-
-By default all properties defined in `eventProperties` are required to be present in the payload for the event.
-This can be overriden by specifying an array of properties which are required here.
-This is equivalent to using the `required` keyword in JSON schema.
-
-#### eventProperties
-
-Object with properties mapping to a JSON schema of that property that specifies what's valid to send in the event.
-This is equivalent to using the `properties` keyword in JSON schema, except that the properties specified are by default required and additional properties are not allowed.
-See [this guide][guide] for an introduction to writing JSON schemas.
-
-The forwardTo and broadcastTo can be combined such that specifying `"controller"` as the forwardTo value and `"instance"` as the broadcastTo value will cause the event to be broadcast to all instances in the cluster.
-For this to work, you will need to specify `instance-host`, `host-controller`, `controller-host`, and `host-instance` as the links.
-
-Keep in mind when forwarding events that if the target an event is being forwarded to is not online, the event will be dropped.
-Use a request if you need a confirmation that the message was received.
-
-### Definining Requests
-
-Requests are defined as properties of the messages object exported by `plugin` that map to instances of the `Request` class from `lib/link`.
-The name of the property corresponds to the handler invoked on the plugin class.
-The Request constructor takes an object of properties that define the event.
+Messages are defined as items of the `plugin.messages` array exported by `index.js`.
 For example, the following could be defined in `plugin`:

 ```js
-messages: {
-    reportFrobnication: new lib.Request({
-        type: "foo_frobber:report_frobnication",
-        links: ["controller-host", "host-instance"],
-        forwardTo: "instance",
-        requestRequired: ["verbosity"],
-        requestProperties: {
-            "verbosity": { type: "integer" },
-            "special": { type: "boolean" },
-        },
-        responseProperties: {
-            "report": {
-                type: "array",
-                items: { type: "string" },
+messages: [
+    class Frobnicate {
+        static plugin = "foo_frobber"; // Plugin name
+        static type = "request";
+        static src = "controller";
+        static dst = "instance";
+        static jsonSchema = {
+            type: "object",
+            properties: {
+                "verbosity": { type: "integer" },
+                "special": { type: "boolean" },
            },
-        },
-    }),
-},
+            required: ["verbosity"],
+            additionalProperties: false,
+        };
+        constructor(json) {
+            this.verbosity = json.verbosity;
+            this.special = json.special;
+        }
+        static fromJSON(json) {
+            return new Frobnicate(json);
+        }
+        toJSON() {
+            return {
+                verbosity: this.verbosity,
+                special: this.special,
+            };
+        }
+        static Response = {
+            jsonSchema: {
+                type: "object",
+                properties: {
+                    "report": {
+                        type: "array",
+                        items: { type: "string" },
+                    },
+                },
+            },
+            fromJSON(json) {
+                return json
+            }
+        }
+    }
+]
 ```

-This specifies a request that can be sent from the controller to a host, and from a host to an instance.
-The request data must contain the property `verbosity` with an integer number as the value, as well as the `instance_id` property (implied by `forwardTo: "instance"`) and it may also contain a boolean `special` property.
-It also defines that the response sent must contain a `report` property mapping to an array of strings.
-When received by a host, it will also be forwarded to the instance specified by `instance_id`.
+This specifies a request that can be sent from the controller to an instance, being routed through the correct host behind the scenes.
+The request data must contain the property `verbosity` with an integer number as the value, and it may also contain a boolean `special` property.
+It also defines that the response sent may contain a `report` property mapping to an array of strings.

-The following properties are recognized by the Request constructor:
+The following properties are recognized as part of a message class:

-#### type
+#### static plugin

-The message type sent over the wire.
-This must start with the name of the plugin followed by colon and and be unique for the plugin.
-The type of the message sent over the socket will have the suffix `_request` appended to it for the request and `_response` appended to it for the response.
+Must contain the name of the plugin this message is defined by.
+This property is not used in core messages.

-#### links
+#### static type

-An array of strings describing which links this request can be sent over.
-Direction matters; `"controller-host"` means the request can be sent from the controller to the host and the host can reply to the controller, but the host can't send a request to the controller unless `"host-controller"` is also present in the links array.
+A string describing the message type sent over the wire.
+This can be either `"request"` or `"event"`.
+The primary difference is whether they allow for a response.

-The available endpoints are `controller`, `host`, `instance`, and `control`.
-Controller talks with host and control, and host talks to instance.
-The full chain must be specified as the individual links in order for a message to travers multiple hops, (i.e., for a message to go from controller to instance it must have both `"controller-host"` and `"host-instance"` in the links array).
-See `forwardTo` for ways to forward a request to the next link in a chain.
+#### static src

-#### forwardTo
+A string or an array of strings describing where this message is allowed to originate from.
+The available endpoints are `"controller"`, `"host"`, `"instance"`, or `"control"`.
+Messages sent from a different source will be rejected.

-Target to forward the request to.
-Can either be `"controller"` to indicate a host should forward it to the controller when receiving it from an instance, or `"instance"` to indicate it should be forwarded to the instances specified by the `instance_id` request property.
-This works by using a default handler for the request by the links that forward it.
+#### static dst

-#### requestRequired
+A string or array of strings describing where this message may be addressed to.
+The available endpoints are `"controller"`, `"host"`, `"instance"`, or `"control"`.
+If the target is multiple hops away it the message will be forwarded towards its destination by the intermediaries.
+For example a message sent from a control connection an instance will be forwarded by the controller to the relevant host and from the host to the correct instance.
+Messages sent to a different destination will be rejected.

-By default all properties defined in `requestProperties` are required to be present in the payload for the request.
-This can be overriden by specifying an array of properties which are required here.
-This is equivalent to using the `required` keyword in JSON schema.
+#### static jsonSchema

-#### requestProperties
+A JSON schema that specifies what's valid to send in the message.

-Object with properties mapping to a JSON schema of that property that specifies what's valid to send in the request.
-This is equivalent to using the `properties` keyword in JSON schema, except that the properties specified are by default required and additional properties are not allowed.
-See [this guide][guide] for an introduction to writing JSON schemas
+#### toJSON

-#### responseRequired
+Optional method to serialize an instance of the class to a JSON object, see the [documentation for `JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description) for the semantics of this method.
+This should return an object that's valid according to `jsonSchema` and accepted by `fromJSON`, and may be omitted if the default serialisation by `JSON.stringify()` already does this.

-Same as the requestRequired only for the response sent back by the target.
+#### static fromJSON

-#### responseProperties
+Required function to restore the class from a JSON object.
+This function is called when the message reaches its destination and is expected to return an identical instance of the class.
+I.e. the result of `fromJSON(JSON.parse(JSON.stringify(instance)))` should be a complete copy of the message.

-Same as the requestProperties only for the response sent back by the target.
+#### static Response

+Optional [JSON sterilisable class](/docs/devs/json-serialisable-classes.md) that specifies the response to the request.
+Required properties are `jsonSchema` and `fromJSON`.

 ## Sending Link Messages

-Link messages are sent by calling the `.send()` method on the Event/Request instance with the link you want to send it over and the data to send.
-For `InstancePlugin` code the link to the host is the `instance` itself, which is accessible through the `.instance` property of the `InstancePlugin`.
-The `.info` property of the plugin class exposes the data exported from the plugin's `plugin` export.
-In other words:
+Link messages are sent by calling the `.sendTo()` method on a connection object with the destination and the data you want to send, where the data is an instance of one of the defined message classes in plugin.messages.
+For example:

 ```js
 // In an InstancePlugin class
 async frobnicate() {
-    this.info.messages.exampleEvent.send(this.instance, { foo: "bar" });
+    const response = await this.instance.sendTo("controller", new messages.Frobnicate({ 
+        verbosity: 2,
+        special: false,
+    }));
+    console.log(response); // { report: [...] }
 }
 ```

-For the Request class the send method is async and returns the response data received from the target it was sent to, or throws an error if the request failed.
+For classes with `static type = "request"` the send method is async and returns a promise that resolves to the response data received from the target it was sent to, or rejects with an error if the request failed.
+The destination specification can either be the ID of a particular control, host or instance, or one of the keywords used to send to multiple targets at once.

+Example destinations:
+
+```js
+sendTo("controller", message);
+sendTo("allHosts", message);
+sendTo("allControls", message);
+sendTo("allInstances", message);
+sendTo({ hostId: 123 }, message);
+sendTo({ instanceId: 123 }, message);
+sendTo({ controlId: 123 }, message);
+```

 ### Handling connection events

@@ -508,7 +483,7 @@ For example the sending of an event from an `InstancePlugin` class can be stoppe

 ```js
 if (this.host.connected) {
-    this.info.messages.frobnicate.send(this.instance, { foo: "bar" });
+    this.instance.sendTo("controller", new messages.Frobnicate({ foo: "bar" }));
 }
 ```

@@ -617,4 +592,4 @@ class CtlPlugin extends BaseCtlPlugin {
 module.exports = {
    CtlPlugin,
 }
-```
+```
@@ -1,102 +1,47 @@
-"use strict";
-module.exports = {
-	"plugins": [
-		"@typescript-eslint",
-		"node",
-	],
-	"root": true,
-	"env": {
-		"node": true,
-		"commonjs": true,
-		"es2022": true,
+import {
+	defineConfig,
+	globalIgnores,
+} from "eslint/config";
+
+import typescriptEslint from "@typescript-eslint/eslint-plugin";
+import node from "eslint-plugin-node";
+import globals from "globals";
+import tsParser from "@typescript-eslint/parser";
+import js from "@eslint/js";
+import stylistic from "@stylistic/eslint-plugin";
+
+import {
+	FlatCompat,
+} from "@eslint/eslintrc";
+
+const compat = new FlatCompat({
+	baseDirectory: import.meta.dirname,
+	recommendedConfig: js.configs.recommended,
+	allConfig: js.configs.all,
+});
+
+export default defineConfig([{
+	plugins: {
+		"@typescript-eslint": typescriptEslint,
+		"@stylistic": stylistic,
+		node,
 	},

-	"overrides": [
-		{
-			"files": ["{packages,plugins}/**/*.ts?(x)"],
-			"parser": "@typescript-eslint/parser",
-			"extends": [
-				"plugin:@typescript-eslint/recommended",
-			],
-			"rules": {
-				"@typescript-eslint/no-explicit-any": "off",
-				"@typescript-eslint/no-useless-constructor": "error",
-				"@typescript-eslint/no-unused-vars": "off",
-				"@typescript-eslint/triple-slash-reference": "off",
-				"prefer-const": "off",
-			},
+	languageOptions: {
+		globals: {
+			...globals.node,
+			...globals.commonjs,
 		},
-		{
-			"files": ["test/**/*.js", "plugins/*/test/**/*.js"],
-			"env": {
-				"mocha": "true",
-			},
-			"parserOptions": { sourceType: "commonjs" },
-			"rules": {
-				"prefer-arrow-callback": "off",
-				"no-invalid-this": "off",
-				"valid-jsdoc": "off",
-				"node/no-unpublished-import": "off",
-				"node/no-unpublished-require": "off",
-			},
-		},
-		{
-			"files": [
-				"packages/web_ui/src/**/*.ts?(x)",
-				"packages/lib/browser.ts",
-				"{packages,plugins}/*/web/**/*.ts?(x)",
-			],
-			"env": {
-				"browser": true,
-			},
-			"parserOptions": {
-				"sourceType": "module",
-				"ecmaFeatures": {
-					"jsx": true,
-				},
-			},
-			"rules": {
-				"node/callback-return": "off",
-				"node/exports-style": "off",
-				"node/file-extension-in-import": "off",
-				"node/global-require": "off",
-				"node/handle-callback-err": "off",
-				"node/no-callback-literal": "off",
-				"node/no-deprecated-api": "off",
-				"node/no-exports-assign": "off",
-				"node/no-extraneous-import": "off",
-				"node/no-extraneous-require": "off",
-				"node/no-missing-import": "off",
-				"node/no-missing-require": "off",
-				"node/no-mixed-requires": "off",
-				"node/no-new-require": "off",
-				"node/no-path-concat": "off",
-				"node/no-process-env": "off",
-				"node/no-process-exit": "off",
-				"node/no-restricted-require": "off",
-				"node/no-sync": "off",
-				"node/no-unpublished-bin": "off",
-				"node/no-unpublished-import": "off",
-				"node/no-unpublished-require": "off",
-				"node/no-unsupported-features/es-builtins": "off",
-				"node/no-unsupported-features/es-syntax": "off",
-				"node/no-unsupported-features/node-builtins": "off",
-				"node/prefer-global/buffer": "off",
-				"node/prefer-global/console": "off",
-				"node/prefer-global/process": "off",
-				"node/prefer-global/text-decoder": "off",
-				"node/prefer-global/text-encoder": "off",
-				"node/prefer-global/url-search-params": "off",
-				"node/prefer-global/url": "off",
-				"node/prefer-promises/dns": "off",
-				"node/prefer-promises/fs": "off",
-				"node/process-exit-as-throw": "off",
-				"node/shebang": "off",
-			},
-		},
-	],
+	},

 	"rules": {
+		"@stylistic/indent": ["error", "tab", {
+			"ignoredNodes": [
+				"JSXFragment", // TODO: Linter crashes if this is removed
+			],
+			"ignoreComments": true,
+			"SwitchCase": 1, // Indent case statements one level from switch
+		}],
 		"accessor-pairs": "error",
 		"array-bracket-newline": "off",
 		"array-bracket-spacing": ["error", "never"],
@@ -104,26 +49,34 @@ module.exports = {
 		"array-element-newline": "off",
 		"arrow-body-style": "error",
 		"arrow-parens": "off",
-		"arrow-spacing": ["error", { "after": true, "before": true }],
+
+		"arrow-spacing": ["error", {
+			"after": true,
+			"before": true,
+		}],
+
 		"block-scoped-var": "error",
 		"block-spacing": "error",
-		"brace-style": ["error", "1tbs", { "allowSingleLine": true }],
+
+		"brace-style": ["error", "1tbs", {
+			"allowSingleLine": true,
+		}],
+
 		"camelcase": "off",
 		"capitalized-comments": "off",
 		"class-methods-use-this": "off",
-		"comma-dangle": [
-			"error",
-			{
-				"arrays": "always-multiline",
-				"objects": "always-multiline",
-				"imports": "always-multiline",
-				"exports": "always-multiline",
-				"functions": "only-multiline",
-			},
-		],
+
+		"comma-dangle": ["error", {
+			"arrays": "always-multiline",
+			"objects": "always-multiline",
+			"imports": "always-multiline",
+			"exports": "always-multiline",
+			"functions": "only-multiline",
+		}],
+
 		"comma-spacing": "error",
 		"comma-style": ["error", "last"],
-		"complexity": "error",
+		"complexity": ["error", { "max": 25 }],
 		"computed-property-spacing": ["error", "never"],
 		"consistent-return": "error",
 		"consistent-this": "error",
@@ -132,27 +85,36 @@ module.exports = {
 		"default-case-last": "error",
 		"default-param-last": "off",
 		"dot-location": ["error", "property"],
-		"dot-notation": ["error", { "allowPattern": "^[a-z]+(_[a-z]+)*$" }],
+
+		"dot-notation": ["error", {
+			"allowPattern": "^[a-z]+(_[a-z]+)*$",
+		}],
+
 		"eol-last": "error",
 		"eqeqeq": "error",
 		"func-call-spacing": "error",
 		"func-name-matching": "error",
 		"func-names": "off",
+
 		"func-style": ["error", "declaration", {
-			// Allow arrow functions as it better expresses referencing this
-			// of the containing scope, which is unweilding in plain functions.
 			"allowArrowFunctions": true,
 		}],
+
 		"function-call-argument-newline": "off",
 		"function-paren-newline": "off",
-		"generator-star-spacing": ["error", { "before": false, "after": true }],
+
+		"generator-star-spacing": ["error", {
+			"before": false,
+			"after": true,
+		}],
+
 		"grouped-accessor-pairs": "error",
 		"guard-for-in": "error",
 		"id-blacklist": "error",
 		"id-length": "off",
 		"id-match": "error",
 		"implicit-arrow-linebreak": "error",
-		"indent": ["error", "tab", { "SwitchCase": 1 }],
+
 		"indent-legacy": "off",
 		"init-declarations": "off",
 		"jsx-quotes": "error",
@@ -162,10 +124,18 @@ module.exports = {
 		"linebreak-style": ["error", "unix"],
 		"lines-around-comment": "off",
 		"lines-around-directive": "off",
-		"lines-between-class-members": ["error", "always", { "exceptAfterSingleLine": true }],
+
+		"lines-between-class-members": ["error", "always", {
+			"exceptAfterSingleLine": true,
+		}],
+
 		"max-classes-per-file": "off",
 		"max-depth": "error",
-		"max-len": ["error", { "code": 120 }],
+
+		"max-len": ["error", {
+			"code": 120,
+		}],
+
 		"max-lines": "off",
 		"max-lines-per-function": "off",
 		"max-nested-callbacks": "error",
@@ -174,10 +144,12 @@ module.exports = {
 		"max-statements-per-line": "off",
 		"multiline-comment-style": ["error", "separate-lines"],
 		"multiline-ternary": "off",
+
 		"new-cap": ["error", {
-			"capIsNewExceptions": ["StringEnum"],
+			"capIsNewExceptions": ["StringEnum", "StringKey"],
 			"capIsNewExceptionPattern": "^Type\\.",
 		}],
+
 		"new-parens": "error",
 		"newline-after-var": "off",
 		"newline-before-return": "off",
@@ -191,7 +163,11 @@ module.exports = {
 		"no-catch-shadow": "off",
 		"no-confusing-arrow": "error",
 		"no-console": "error",
-		"no-constant-condition": ["error", { "checkLoops": false }],
+
+		"no-constant-condition": ["error", {
+			"checkLoops": false,
+		}],
+
 		"no-constructor-return": "error",
 		"no-continue": "off",
 		"no-div-regex": "error",
@@ -216,16 +192,15 @@ module.exports = {
 		"no-lonely-if": "error",
 		"no-loop-func": "error",
 		"no-magic-numbers": "off",
-		"no-mixed-operators": [
-			"error",
-			{
-				"groups": [
-					["&", "|", "^", "~", "<<", ">>", ">>>"],
-					["==", "!=", "===", "!==", ">", ">=", "<", "<="],
-					["in", "instanceof"],
-				],
-			},
-		],
+
+		"no-mixed-operators": ["error", {
+			"groups": [
+				["&", "|", "^", "~", "<<", ">>", ">>>"],
+				["==", "!=", "===", "!==", ">", ">=", "<", "<="],
+				["in", "instanceof"],
+			],
+		}],
+
 		"no-multi-assign": "error",
 		"no-multi-spaces": "error",
 		"no-multi-str": "error",
@@ -240,7 +215,11 @@ module.exports = {
 		"no-new-wrappers": "error",
 		"no-octal-escape": "error",
 		"no-param-reassign": "off",
-		"no-plusplus": ["error", { "allowForLoopAfterthoughts": true }],
+
+		"no-plusplus": ["error", {
+			"allowForLoopAfterthoughts": true,
+		}],
+
 		"no-proto": "error",
 		"no-restricted-exports": "error",
 		"no-restricted-globals": "error",
@@ -252,9 +231,15 @@ module.exports = {
 		"no-script-url": "error",
 		"no-self-compare": "error",
 		"no-sequences": "error",
-		"no-shadow": ["error", { "allow": ["Event", "Request", "yargs"] }],
+
+		"no-shadow": ["error", {
+			"allow": ["Event", "Request", "yargs"],
+		}],
+
 		"no-spaced-func": "error",
-		"no-tabs": ["error", { "allowIndentationTabs": true }],
+
+		"no-tabs": "off",
+
 		"no-template-curly-in-string": "error",
 		"no-ternary": "off",
 		"no-throw-literal": "error",
@@ -273,7 +258,11 @@ module.exports = {
 		"no-useless-rename": "error",
 		"no-useless-return": "error",
 		"no-var": "error",
-		"no-void": ["error", { "allowAsStatement": true }],
+
+		"no-void": ["error", {
+			"allowAsStatement": true,
+		}],
+
 		"no-warning-comments": "off",
 		"no-whitespace-before-property": "error",
 		"nonblock-statement-body-position": "error",
@@ -283,6 +272,7 @@ module.exports = {
 		"one-var": "off",
 		"one-var-declaration-per-line": "error",
 		"operator-assignment": "off",
+
 		"operator-linebreak": ["error", "after", {
 			"overrides": {
 				"?": "before",
@@ -292,6 +282,7 @@ module.exports = {
 				"??": "before",
 			},
 		}],
+
 		"padded-blocks": "off",
 		"padding-line-between-statements": "error",
 		"prefer-arrow-callback": "error",
@@ -308,9 +299,13 @@ module.exports = {
 		"prefer-spread": "error",
 		"prefer-template": "error",
 		"quote-props": "off",
-		"quotes": ["error", "double", { "avoidEscape": true }],
+
+		"quotes": ["error", "double", {
+			"avoidEscape": true,
+		}],
+
 		"radix": ["error", "always"],
-		"require-atomic-updates": "off", // XXX Not sure why this triggers on process.title = ...
+		"require-atomic-updates": "off",
 		"require-await": "off",
 		"require-jsdoc": "off",
 		"require-unicode-regexp": "off",
@@ -326,73 +321,183 @@ module.exports = {
 		"space-in-parens": ["error", "never"],
 		"space-infix-ops": "off",
 		"space-unary-ops": "error",
+
 		"spaced-comment": ["error", "always", {
 			"line": {
 				"markers": ["/"],
 			},
 		}],
-		"strict": "error",
+
 		"switch-colon-spacing": "error",
 		"symbol-description": "error",
 		"template-curly-spacing": ["error", "never"],
 		"template-tag-spacing": "error",
 		"unicode-bom": ["error", "never"],
-		"valid-jsdoc": ["error", {
-			"requireReturn": false,
-			"requireReturnType": false,
-			"requireParamType": false,
-		}],
+
 		"vars-on-top": "error",
 		"wrap-iife": "error",
 		"wrap-regex": "off",
 		"yield-star-spacing": "error",
-		"yoda": ["error", "never", { "exceptRange": true }],
+
+		"yoda": ["error", "never", {
+			"exceptRange": true,
+		}],

 		"node/callback-return": "off",
 		"node/exports-style": "off",
 		"node/file-extension-in-import": "off",
 		"node/global-require": "off",
-		// Node.js callback passing style of (err, value) is not used in this project
 		"node/handle-callback-err": "off",
 		"node/no-callback-literal": "off",
-		"node/no-deprecated-api": "error",
-		"node/no-exports-assign": "error",
+		"node/no-deprecated-api": "off",
+		"node/no-exports-assign": "off",
 		"node/no-extraneous-import": "off",
 		"node/no-extraneous-require": "off",
-		"node/no-missing-import": ["error", {
-			"tryExtensions": [".js", ".ts"],
-		}],
-		"node/no-missing-require": "error",
-		"node/no-mixed-requires": "error",
-		"node/no-new-require": "error",
-		"node/no-path-concat": "error",
-		"node/no-process-env": "error",
-		"node/no-process-exit": "error",
+
+		"node/no-missing-import": "off",
+
+		"node/no-missing-require": "off",
+		"node/no-mixed-requires": "off",
+		"node/no-new-require": "off",
+		"node/no-path-concat": "off",
+		"node/no-process-env": "off",
+		"node/no-process-exit": "off",
 		"node/no-restricted-require": "off",
 		"node/no-sync": "error",
-		"node/no-unpublished-bin": "error",
-		"node/no-unpublished-import": "error",
-		"node/no-unpublished-require": [
-			"error",
-			{ "allowModules": ["webpack", "webpack-merge", "webpack-dev-middleware"] },
-		],
+		"node/no-unpublished-bin": "off",
+		"node/no-unpublished-import": "off",
+
+		"node/no-unpublished-require": "off",
+
 		"node/no-unsupported-features/es-builtins": "off",
 		"node/no-unsupported-features/es-syntax": "off",
 		"node/no-unsupported-features/node-builtins": "off",
-		"node/prefer-global/buffer": "error",
-		"node/prefer-global/console": "error",
-		"node/prefer-global/process": "error",
-		"node/prefer-global/text-decoder": "error",
-		"node/prefer-global/text-encoder": "error",
-		"node/prefer-global/url-search-params": "error",
-		"node/prefer-global/url": "error",
+		"node/prefer-global/buffer": "off",
+		"node/prefer-global/console": "off",
+		"node/prefer-global/process": "off",
+		"node/prefer-global/text-decoder": "off",
+		"node/prefer-global/text-encoder": "off",
+		"node/prefer-global/url-search-params": "off",
+		"node/prefer-global/url": "off",
 		"node/prefer-promises/dns": "off",
 		"node/prefer-promises/fs": "off",
-		"node/process-exit-as-throw": "error",
-		"node/shebang": ["error", {
-			"convertPath": {
-				"*.ts": ["^(.+)\\.ts$", "dist/node/$1.js"],
-			},
-		}],
+		"node/process-exit-as-throw": "off",
+
+		"node/shebang": "off",
 	},
-};
+}, {
+	files: ["{packages,plugins}/**/*.ts?(x)"],
+
+	languageOptions: {
+		parser: tsParser,
+	},
+
+	extends: compat.extends("plugin:@typescript-eslint/recommended"),
+
+	"rules": {
+		"@typescript-eslint/no-explicit-any": "off",
+		"@typescript-eslint/no-useless-constructor": "error",
+		"@typescript-eslint/no-unused-vars": "off",
+		"@typescript-eslint/triple-slash-reference": "off",
+
+		"@typescript-eslint/no-shadow": ["error", {
+			"allow": ["Event", "Request", "yargs"],
+		}],
+
+		// Allow require imports where necessary (dynamic loading, webpack configs, etc.)
+		"@typescript-eslint/no-require-imports": "off",
+
+		"prefer-const": "off",
+		"no-shadow": "off",
+	},
+}, {
+	files: ["test/**/*.js", "plugins/*/test/**/*.js"],
+
+	languageOptions: {
+		globals: {
+			...globals.mocha,
+		},
+
+		sourceType: "commonjs",
+		parserOptions: {},
+	},
+
+	"rules": {
+		"prefer-arrow-callback": "off",
+		"no-invalid-this": "off",
+		"node/no-unpublished-import": "off",
+		"node/no-unpublished-require": "off",
+	},
+}, {
+	files: [
+		"packages/web_ui/src/**/*.ts?(x)",
+		"packages/lib/browser.ts",
+		"packages/create/templates/*/web/**/*.{t,j}s?(x)",
+		"{packages,plugins}/*/web/**/*.ts?(x)",
+	],
+
+	languageOptions: {
+		globals: {
+			...globals.browser,
+		},
+
+		"sourceType": "module",
+
+		parserOptions: {
+			"ecmaFeatures": {
+				"jsx": true,
+			},
+		},
+	},
+
+	"rules": {
+		"node/callback-return": "off",
+		"node/exports-style": "off",
+		"node/file-extension-in-import": "off",
+		"node/global-require": "off",
+		"node/handle-callback-err": "off",
+		"node/no-callback-literal": "off",
+		"node/no-deprecated-api": "off",
+		"node/no-exports-assign": "off",
+		"node/no-extraneous-import": "off",
+		"node/no-extraneous-require": "off",
+		"node/no-missing-import": "off",
+		"node/no-missing-require": "off",
+		"node/no-mixed-requires": "off",
+		"node/no-new-require": "off",
+		"node/no-path-concat": "off",
+		"node/no-process-env": "off",
+		"node/no-process-exit": "off",
+		"node/no-restricted-require": "off",
+		"node/no-sync": "error",
+		"node/no-unpublished-bin": "off",
+		"node/no-unpublished-import": "off",
+		"node/no-unpublished-require": "off",
+		"node/no-unsupported-features/es-builtins": "off",
+		"node/no-unsupported-features/es-syntax": "off",
+		"node/no-unsupported-features/node-builtins": "off",
+		"node/prefer-global/buffer": "off",
+		"node/prefer-global/console": "off",
+		"node/prefer-global/process": "off",
+		"node/prefer-global/text-decoder": "off",
+		"node/prefer-global/text-encoder": "off",
+		"node/prefer-global/url-search-params": "off",
+		"node/prefer-global/url": "off",
+		"node/prefer-promises/dns": "off",
+		"node/prefer-promises/fs": "off",
+		"node/process-exit-as-throw": "off",
+		"node/shebang": "off",
+	},
+}, {
+	files: ["packages/create/templates/**/*.{t,j}s?(x)"],
+
+	"rules": {
+		"node/no-missing-require": "off",
+		"node/no-missing-import": "off",
+		"@stylistic/indent": "off",
+		"spaced-comment": "off",
+		"comma-spacing": "off",
+		"max-len": "off",
+		"indent": "off",
+	},
+}, globalIgnores(["**/dist/", "dist/"])]);
@@ -1,16 +1,21 @@
 {
 	"name": "root",
 	"private": true,
+	"files": [],
+	"packageManager": "pnpm@10.28.1+sha512.7d7dbbca9e99447b7c3bf7a73286afaaf6be99251eb9498baefa7d406892f67b879adb3a1d7e687fc4ccc1a388c7175fbaae567a26ab44d1067b54fcb0d6a316",
 	"scripts": {
 		"build": "tsc --build",
 		"watch": "tsc --build --watch",
-		"test": "pnpm run build && mocha --check-leaks -R spec --recursive test \"plugins/*/test/**\"",
+		"build-mod": "pnpm run -r build-mod --output-dir ../../dist",
+		"test": "pnpm run build && NODE_EXTRA_CA_CERTS=$(pwd)/test/file/tls/cert.pem mocha --enable-source-maps --check-leaks -R spec --recursive test \"plugins/*/test/**\" --exclude \"test/manual/**\"",
+		"silent-test": "SILENT_TEST=y pnpm test",
 		"fast-test": "FAST_TEST=y pnpm test",
 		"cover": "nyc pnpm test",
 		"fast-cover": "FAST_TEST=y nyc pnpm test",
 		"ci-cover": "nyc --reporter=lcovonly pnpm run-script test",
 		"lint": "eslint packages plugins test",
 		"lint-fix": "eslint --fix packages plugins test",
+		"clean": "node ./clean.js",
 		"docs": "typedoc",
 		"bundle-dependencies": "bundle-dependencies"
 	},
@@ -21,27 +26,38 @@
 		]
 	},
 	"engines": {
-		"node": ">=18"
+		"node": ">=20"
 	},
+	"workspaces": [
+		"packages/*",
+		"plugins/*",
+		"external_plugins/*",
+		"external_plugins/*/*"
+	],
 	"devDependencies": {
 		"@clusterio/controller": "workspace:*",
 		"@clusterio/ctl": "workspace:*",
 		"@clusterio/host": "workspace:*",
 		"@clusterio/lib": "workspace:*",
-		"@swc/core": "^1.4.0",
-		"@typescript-eslint/eslint-plugin": "^6.4.1",
-		"@typescript-eslint/parser": "^6.4.1",
-		"eslint": "^8.45.0",
+		"@clusterio/web_ui": "workspace:*",
+		"@eslint/eslintrc": "^3.3.1",
+		"@eslint/js": "^9.32.0",
+		"@stylistic/eslint-plugin": "^5.2.2",
+		"@swc/core": "^1.13.3",
+		"@typescript-eslint/eslint-plugin": "^8.38.0",
+		"@typescript-eslint/parser": "^8.38.0",
+		"eslint": "^9.32.0",
 		"eslint-plugin-node": "^11.1.0",
-		"express": "^4.18.2",
-		"form-data": "^4.0.0",
-		"fs-extra": "^11.1.1",
-		"jsonwebtoken": "^9.0.1",
-		"jszip": "^3.10.0",
-		"mocha": "^10.2.0",
-		"nyc": "^15.1.0",
-		"phin": "^3.7.0",
-		"typedoc": "^0.24.8",
-		"typescript": "^5.1.6"
+		"express": "^5.1.0",
+		"form-data": "^4.0.4",
+		"fs-extra": "^11.3.0",
+		"globals": "^16.3.0",
+		"jsonwebtoken": "^9.0.2",
+		"jszip": "^3.10.1",
+		"mocha": "^11.7.1",
+		"nyc": "^17.1.0",
+		"typedoc": "^0.28.9",
+		"typescript": "^5.9.2",
+		"yargs": "^18.0.0"
 	}
 }
@@ -32,6 +32,7 @@ const { ConsoleTransport, levels, logger } = lib;

 import Controller from "./src/Controller";
 import UserManager from "./src/UserManager";
+import UserRecord from "./src/UserRecord";
 import { version } from "./package.json";

 // globals
@@ -66,9 +67,9 @@ void new lib.Gauge(
 			if (!controller || !controller.hosts) {
 				return;
 			}
-			for (let [id, host] of controller.hosts) {
+			for (const host of controller.hosts.values()) {
 				gauge.labels({
-					host_id: String(id),
+					host_id: String(host.id),
 					host_name: host.name,
 				}).set(1);
 			};
@@ -86,9 +87,9 @@ void new lib.Gauge(
 			if (!controller || !controller.instances) {
 				return;
 			}
-			for (let [id, instance] of controller.instances) {
+			for (const instance of controller.instances.values()) {
 				gauge.labels({
-					instance_id: String(id),
+					instance_id: String(instance.id),
 					instance_name: String(instance.config.get("instance.name")),
 					host_id: String(instance.config.get("instance.assigned_host")),
 				}).set(1);
@@ -127,37 +128,55 @@ void new lib.Gauge(

 async function handleBootstrapCommand(
 	args: any,
-	controllerConfig: lib.ControllerConfig
+	controllerConfig: lib.ControllerConfig,
+	controllerConfigLock: lib.LockFile,
 ): Promise<void> {
 	let subCommand = args._[1];
-	let userManager = new UserManager(controllerConfig);
-	await userManager.load(path.join(controllerConfig.get("controller.database_directory"), "users.json"));
+
+	const databaseDirectory = controllerConfig.get("controller.database_directory");
+	await UserManager.attemptMigrateLegacyUsersFile(
+		path.join(databaseDirectory, "users.json"),
+		path.join(databaseDirectory, "roles.json"),
+	);
+
+	const roles = new lib.SubscribableDatastore(...await new lib.JsonIdDatastoreProvider(
+		path.join(databaseDirectory, "roles.json"),
+		lib.Role.fromJSON.bind(lib.Role),
+	).bootstrap());
+
+	const users = new lib.SubscribableDatastore(...await new lib.JsonIdDatastoreProvider(
+		path.join(databaseDirectory, "users.json"),
+		UserRecord.fromJSON.bind(UserRecord),
+	).bootstrap());
+
+	const userManager = new UserManager(users, roles, controllerConfig);
+
 	if (subCommand === "create-admin") {
+		await controllerConfigLock.acquire(); // Also needed to write to the database files
+
 		if (!args.name) {
 			logger.error("name cannot be blank");
 			process.exitCode = 1;
 			return;
 		}

-		let admin = userManager.users.get(args.name);
-		if (!admin) {
-			admin = userManager.createUser(args.name);
-		}
+		const user = userManager.getOrCreateUser(args.name);
+		user.roleIds.add(lib.Role.DefaultAdminRoleId);
+		user.isAdmin = true;
+		user.saveRecord();

-		let adminRole = lib.ensureDefaultAdminRole(userManager.roles);
-		admin.roleIds.add(adminRole.id);
-		admin.isAdmin = true;
-		await userManager.save(path.join(controllerConfig.get("controller.database_directory"), "users.json"));
+		await userManager.records.save();
+		await controllerConfigLock.release();

 	} else if (subCommand === "generate-user-token") {
-		let user = userManager.users.get(args.name);
+		let user = userManager.getByName(args.name);
 		if (!user) {
 			logger.error(`No user named '${args.name}'`);
 			process.exitCode = 1;
 			return;
 		}
 		// eslint-disable-next-line no-console
-		console.log(userManager.signUserToken(user.name));
+		console.log(userManager.signUserToken(user));

 	} else if (subCommand === "generate-host-token") {
 		// eslint-disable-next-line no-console
@@ -167,7 +186,7 @@ async function handleBootstrapCommand(
 		));

 	} else if (subCommand === "create-ctl-config") {
-		let admin = userManager.users.get(args.name);
+		let admin = userManager.getByName(args.name);
 		if (!admin) {
 			logger.error(`No user named '${args.name}'`);
 			process.exitCode = 1;
@@ -178,7 +197,7 @@ async function handleBootstrapCommand(
 		controlConfig.set("control.controller_url", Controller.calculateControllerUrl(controllerConfig));
 		controlConfig.set(
 			"control.controller_token",
-			userManager.signUserToken(admin.name),
+			userManager.signUserToken(admin),
 		);

 		let content = JSON.stringify(controlConfig, null, "\t");
@@ -210,7 +229,6 @@ interface InitializeParameters {
 	shouldRun: boolean;
 	clusterLogger: winston.Logger;
 	pluginInfos: lib.PluginNodeEnvInfo[] | null;
-	controllerConfigPath: string | null;
 	controllerConfig: lib.ControllerConfig | null;
 }

@@ -244,12 +262,17 @@ async function initialize(): Promise<InitializeParameters> {
 			default: "plugin-list.json",
 			type: "string",
 		})
+		.option("bypass-lock-file", { hidden: true, type: "boolean", nargs: 0, default: false })
 		.command("plugin", "Manage available plugins", lib.pluginCommand)
 		.command("config", "Manage Controller config", lib.configCommand)
 		.command("bootstrap", "Bootstrap access to cluster", yargs => {
 			yargs
-				.command("create-admin <name>", "Create a cluster admin")
-				.command("generate-user-token <name>", "Generate authentication token for the given user")
+				.command("create-admin <name>", "Create a cluster admin", yargs => {
+					yargs.positional("name", { describe: "Name of the admin user", type: "string" });
+				})
+				.command("generate-user-token <name>", "Generate authentication token for the given user", yargs => {
+					yargs.positional("name", { describe: "Name of the user", type: "string" });
+				})
 				.command("generate-host-token <id>", "Generate authentication token for the given host", yargs => {
 					yargs.positional("id", { describe: "ID of the host", type: "number" });
 				})
@@ -266,6 +289,11 @@ async function initialize(): Promise<InitializeParameters> {
 				type: "boolean", nargs: 0, default: false,
 				describe: "Indicate that a process monitor will restart the controller on failure",
 			});
+			yargs.option("recovery", {
+				type: "boolean", nargs: 0, default: false,
+				describe: "Start the controller in recovery mode with all plugins disabled and hosts disconnected",
+			});
+			yargs.option("check-user-count", { hidden: true, type: "boolean", nargs: 0, default: true });
 			yargs.option("dev", { hidden: true, type: "boolean", nargs: 0 });
 			yargs.option("dev-plugin", { hidden: true, type: "array" });
 		})
@@ -309,18 +337,14 @@ async function initialize(): Promise<InitializeParameters> {
 	let shouldRun = false;
 	if (command === "run") {
 		logger.info(`Starting Clusterio controller ${version}`);
+		if (args.recovery) {
+			logger.warn("Controller recovery mode enabled. Some features will be disabled.");
+		}
 		shouldRun = true;
 	}

 	logger.info(`Loading available plugins from ${args.pluginList}`);
-	let pluginList = new Map();
-	try {
-		pluginList = new Map(JSON.parse(await fs.readFile(args.pluginList, { encoding: "utf8" })));
-	} catch (err: any) {
-		if (err.code !== "ENOENT") {
-			throw err;
-		}
-	}
+	let pluginList = await lib.loadPluginList(args.pluginList);

 	// If the command is plugin management we don't try to load plugins
 	if (command === "plugin") {
@@ -330,7 +354,6 @@ async function initialize(): Promise<InitializeParameters> {
 			shouldRun,
 			clusterLogger,
 			pluginInfos: null,
-			controllerConfigPath: null,
 			controllerConfig: null,
 		};
 	}
@@ -341,46 +364,49 @@ async function initialize(): Promise<InitializeParameters> {
 	lib.addPluginConfigFields(pluginInfos);

 	const controllerConfigPath = args.config;
+	const controllerConfigLockPath = `${controllerConfigPath}.lock`;
+	if (args.bypassLockFile) {
+		await fs.unlink(controllerConfigLockPath).catch(() => {}); // ignore error, file might not exist
+	}
+
+	let controllerConfig;
+	const controllerConfigLock = new lib.LockFile(controllerConfigLockPath);
 	logger.info(`Loading config from ${controllerConfigPath}`);
-	let controllerConfig = new lib.ControllerConfig("controller");
 	try {
-		let jsonConfig = JSON.parse(await fs.readFile(controllerConfigPath, { encoding: "utf8" }));
-		controllerConfig = lib.ControllerConfig.fromJSON(jsonConfig, "controller");
+		controllerConfig = await lib.ControllerConfig.fromFile("controller", controllerConfigPath);

 	} catch (err: any) {
 		if (err.code === "ENOENT") {
 			logger.info("Config not found, initializing new config");
-			controllerConfig = new lib.ControllerConfig("controller");
+			controllerConfig = new lib.ControllerConfig("controller", undefined, controllerConfigPath);

 		} else {
-			throw new lib.StartupError(`Failed to load ${controllerConfigPath}: ${err.message}`);
+			throw new lib.StartupError(`Failed to load ${controllerConfigPath}: ${err.stack ?? err.message ?? err}`);
 		}
 	}

+	controllerConfig.set("controller.version", version); // Allows tracking last loaded version
+
 	if (!controllerConfig.get("controller.auth_secret")) {
 		logger.info("Generating new controller authentication secret");
 		let asyncRandomBytes = util.promisify(crypto.randomBytes);
 		let bytes = await asyncRandomBytes(256);
 		controllerConfig.set("controller.auth_secret", bytes.toString("base64"));
-		await lib.safeOutputFile(
-			controllerConfigPath, JSON.stringify(controllerConfig, null, "\t")
-		);
+		await controllerConfig.save();
 	}

 	if (command === "config") {
-		await lib.handleConfigCommand(
-			args, controllerConfig, controllerConfigPath
-		);
-
+		await lib.handleConfigCommand(args, controllerConfig, controllerConfigLock);
 	} else if (command === "bootstrap") {
-		await handleBootstrapCommand(args, controllerConfig);
+		await handleBootstrapCommand(args, controllerConfig, controllerConfigLock);
+	} else if (shouldRun) {
+		await controllerConfigLock.acquire(); // Hold the lock until process exit
 	}

 	return {
 		args,
 		clusterLogger,
 		pluginInfos,
-		controllerConfigPath,
 		controllerConfig,
 		shouldRun,
 	};
@@ -396,28 +422,35 @@ async function startup() {
 		shouldRun,
 		clusterLogger,
 		pluginInfos,
-		controllerConfigPath,
 		controllerConfig,
 	} = await initialize();
-	if (!shouldRun || !pluginInfos || !controllerConfigPath || !controllerConfig) {
+	if (!shouldRun || !pluginInfos || !controllerConfig) {
 		return;
 	}

 	controller = new Controller(
 		clusterLogger,
 		pluginInfos,
-		controllerConfigPath,
 		controllerConfig,
 		Boolean(args.canRestart),
+		Boolean(args.recovery),
 		...await Controller.bootstrap(controllerConfig)
 	);

+	// Refuse to start if there are no users loaded
+	if (args.checkUserCount && controller.users.records.size === 0) {
+		logger.fatal(
+			"Cannot start controller, no users loaded.\n" +
+			"Try `npx clusteriocontroller bootstrap create-admin <username>`");
+		process.exit(1);
+	}
+
 	let secondSigint = false;
 	process.on("SIGINT", () => {
 		if (secondSigint) {
 			setBlocking(true);
 			logger.fatal("Caught second interrupt, terminating immediately");
-			// eslint-disable-next-line node/no-process-exit
+
 			process.exit(1);
 		}

@@ -430,7 +463,7 @@ async function startup() {
 		if (secondSigterm) {
 			setBlocking(true);
 			logger.fatal("Caught second termination, terminating immediately");
-			// eslint-disable-next-line node/no-process-exit
+
 			process.exit(1);
 		}

@@ -457,7 +490,7 @@ I           version of clusterio.  Expect things to break. I
 `
 	);
 	startup().catch(err => {
-		if (err instanceof lib.StartupError) {
+		if (err instanceof lib.StartupError || err.code === "InstallationError") {
 			logger.fatal(`
 +-------------------------------+
 | Unable to to start controller |
@@ -1,12 +1,15 @@
 import { bootstrap } from "./controller";
 export { default as Controller } from "./src/Controller";
-export { default as ControllerUser } from "./src/ControllerUser";
 export { default as ControllerRouter } from "./src/ControllerRouter";
 export { default as ControlConnection } from "./src/ControlConnection";
 export { default as HostConnection } from "./src/HostConnection";
-export { default as InstanceInfo } from "./src/InstanceInfo";
+export { default as InstanceRecord } from "./src/InstanceRecord";
+export { default as InstanceManager } from "./src/InstanceManager";
+export { default as HostRecord } from "./src/HostRecord";
 export { default as BaseControllerPlugin } from "./src/BaseControllerPlugin";
 export { default as UserManager } from "./src/UserManager";
+export { default as UserRecord } from "./src/UserRecord";
+export { default as User } from "./src/User";
 export { default as WsServer } from "./src/WsServer";

 if (module === require.main) {
@@ -3,56 +3,59 @@
 	"description": "Implementation of Clusterio controller",
 	"author": "Hornwitser",
 	"license": "MIT",
-	"version": "2.0.0-alpha.17",
+	"version": "2.0.0-alpha.23",
 	"main": "dist/node/index.js",
 	"scripts": {
-		"prepare": "tsc --build && webpack-cli --env production",
+		"prepare": "tsc --build && webpack-cli --mode production",
 		"test": "echo \"Error: no test specified\" && exit 1"
 	},
 	"bin": {
 		"clusteriocontroller": "./dist/node/controller.js"
 	},
 	"keywords": [
+		"clusterio",
 		"factorio"
 	],
 	"engines": {
-		"node": ">=18"
+		"node": ">=20"
 	},
 	"dependencies": {
-		"@clusterio/lib": "^2.0.0-alpha.17",
-		"@sinclair/typebox": "^0.30.4",
+		"@clusterio/lib": "workspace:*",
+		"@sinclair/typebox": "catalog:",
+		"set-blocking": "catalog:",
+		"jsonwebtoken": "catalog:",
+		"express": "catalog:",
+		"fs-extra": "catalog:",
+		"ws": "catalog:",
+		"jszip": "catalog:",
+		"winston": "catalog:",
+		"winston-daily-rotate-file": "catalog:",
 		"busboy": "^1.6.0",
-		"compression": "^1.7.4",
-		"express": "^4.18.2",
-		"fs-extra": "^11.1.1",
-		"jsonwebtoken": "^9.0.1",
-		"jszip": "^3.10.1",
-		"set-blocking": "^2.0.0",
-		"webpack-cli": "^5.1.4",
-		"winston": "^3.10.0",
-		"winston-daily-rotate-file": "^4.7.1",
-		"ws": "^8.13.0",
+		"compression": "^1.8.0",
+		"finalhandler": "^1.3.1",
 		"yargs": "^17.7.2"
 	},
 	"devDependencies": {
-		"@clusterio/web_ui": "^2.0.0-alpha.17",
-		"@swc/core": "^1.4.0",
-		"@types/busboy": "^1.5.0",
+		"@clusterio/web_ui": "workspace:*",
+		"@types/jsonwebtoken": "catalog:",
+		"@types/set-blocking": "catalog:",
+		"@types/finalhandler": "catalog:",
+		"@types/express": "catalog:",
+		"@types/fs-extra": "catalog:",
+		"@types/node": "catalog:",
+		"@types/ws": "catalog:",
+		"@types/yargs": "^17.0.33",
 		"@types/compression": "^1.7.2",
-		"@types/express": "^4.17.17",
-		"@types/fs-extra": "^11.0.1",
-		"@types/jsonwebtoken": "^9.0.2",
-		"@types/node": "^20.4.5",
-		"@types/set-blocking": "^2.0.0",
-		"@types/ws": "^8.5.5",
-		"@types/yargs": "^17.0.24",
-		"react": "^18.2.0",
-		"react-dom": "^18.2.0",
-		"react-router-dom": "^6.4.14",
-		"typescript": "^5.1.6",
-		"webpack": "^5.88.2",
-		"webpack-dev-middleware": "^6.1.1",
-		"webpack-merge": "^5.9.0"
+		"@types/busboy": "^1.5.0",
+		"@swc/core": "catalog:",
+		"react": "catalog:",
+		"react-dom": "catalog:",
+		"react-router-dom": "catalog:",
+		"typescript": "catalog:",
+		"webpack": "catalog:",
+		"webpack-cli": "catalog:",
+		"webpack-merge": "catalog:",
+		"webpack-dev-middleware": "^6.1.1"
 	},
 	"publishConfig": {
 		"access": "public"
@@ -16,7 +16,7 @@ import * as routes from "./routes";
 * @alias module:controller/src/BaseConnection
 */
 export default class BaseConnection extends lib.Link {
-	declare ["connector"]: WsServerConnector;
+	declare "connector": WsServerConnector;

 	constructor(
 		connector: lib.WebSocketBaseConnector,
@@ -32,16 +32,17 @@ export default class BaseConnection extends lib.Link {
 		this.handle(lib.ModPackGetRequest, this.handleModPackGetRequest.bind(this));
 		this.handle(lib.ModPackGetDefaultRequest, this.handleModPackGetDefaultRequest.bind(this));
 		this.handle(lib.ModDownloadRequest, this.handleModDownloadRequest.bind(this));
+		this.handle(lib.FactorioVersionsRequest, this.handleFactorioVersionsRequest.bind(this));

 		this.handle(lib.SubscriptionRequest, this.handleSubscriptionRequest.bind(this));
 		this.connector.on("close", () => {
-			this._controller.subscriptions.unsubscribe(this);
+			this._controller.subscriptions.unsubscribeLink(this);
 		});
 	}

 	async disconnect(code: number, reason: string) {
 		try {
-			await this.connector.disconnect();
+			await this.connector.disconnect(code, reason);
 		} catch (err: any) {
 			if (!(err instanceof lib.SessionLost)) {
 				logger.error(`"Unexpected error preparing disconnect:\n${err.stack}`);
@@ -78,7 +79,7 @@ export default class BaseConnection extends lib.Link {
 		return modPack;
 	}

-	getMod(mod: { name: string, version: string, sha1?: string }) {
+	getMod(mod: { name: string, version: lib.FullVersion, sha1?: string }) {
 		let filename = lib.ModInfo.filename(mod.name, mod.version);
 		let modInfo = this._controller.modStore.files.get(filename);
 		if (!modInfo) {
@@ -106,4 +107,8 @@ export default class BaseConnection extends lib.Link {
 	async handleSubscriptionRequest(request: lib.SubscriptionRequest, src: lib.Address, dst: lib.Address) {
 		return await this._controller.subscriptions.handleRequest(this, request, src, dst);
 	}
+
+	async handleFactorioVersionsRequest(request: lib.FactorioVersionsRequest) {
+		return await this._controller.factorioVersions.get(request.maxAgeMs);
+	}
 }
@@ -3,7 +3,7 @@ import type {
 	ModPack, ModInfo, PlayerEvent, PluginNodeEnvInfo,
 } from "@clusterio/lib";
 import type Controller from "./Controller";
-import type InstanceInfo from "./InstanceInfo";
+import type InstanceRecord from "./InstanceRecord";
 import type ControlConnection from "./ControlConnection";
 import type HostConnection from "./HostConnection";

@@ -91,7 +91,7 @@ export default class BaseControllerPlugin {
 	 *     The instance that changed.
 	 * @param prev - the previous status of the instance.
 	 */
-	async onInstanceStatusChanged(instance: InstanceInfo, prev?: InstanceStatus) { }
+	async onInstanceStatusChanged(instance: InstanceRecord, prev?: InstanceStatus) { }

 	/**
 	 * Called when the value of a controller config field changed.
@@ -117,7 +117,7 @@ export default class BaseControllerPlugin {
 	 * @param curr - The current value of the field.
 	 * @param prev - The previous value of the field.
 	 */
-	async onInstanceConfigFieldChanged(instance: InstanceInfo, field: string, curr: unknown, prev: unknown) { }
+	async onInstanceConfigFieldChanged(instance: InstanceRecord, field: string, curr: unknown, prev: unknown) { }

 	/**
 	 * Called before collecting Prometheus metrics
@@ -261,7 +261,7 @@ export default class BaseControllerPlugin {
 	 *     The instance it occured on.
 	 * @param event - Information about the event.
 	 */
-	async onPlayerEvent(instance: InstanceInfo, event: PlayerEvent) { }
+	async onPlayerEvent(instance: InstanceRecord, event: PlayerEvent) { }

 	/**
 	 * Broadcast event to all connected hosts
@@ -6,7 +6,8 @@ import * as lib from "@clusterio/lib";
 const { logFilter, logger } = lib;

 import BaseConnection from "./BaseConnection";
-import ControllerUser from "./ControllerUser";
+import User from "./User";
+import UserRecord from "./UserRecord";
 import * as routes from "./routes";
 import Controller from "./Controller";

@@ -40,7 +41,7 @@ export default class ControlConnection extends BaseConnection {
 		registerData: { version: string },
 		connector: WsServerConnector,
 		controller: Controller,
-		public user: ControllerUser, // The user making this connection.
+		public user: User, // The user making this connection.
 		public id: number
 	) {
 		super(connector, controller);
@@ -70,6 +71,7 @@ export default class ControlConnection extends BaseConnection {

 		this.handle(lib.ControllerStopRequest, this.handleControllerStopRequest.bind(this));
 		this.handle(lib.ControllerRestartRequest, this.handleControllerRestartRequest.bind(this));
+		this.handle(lib.ControllerUpdateRequest, this.handleControllerUpdateRequest.bind(this));
 		this.handle(lib.ControllerConfigGetRequest, this.handleControllerConfigGetRequest.bind(this));
 		this.handle(lib.ControllerConfigSetFieldRequest, this.handleControllerConfigSetFieldRequest.bind(this));
 		this.handle(lib.ControllerConfigSetPropRequest, this.handleControllerConfigSetPropRequest.bind(this));
@@ -98,6 +100,9 @@ export default class ControlConnection extends BaseConnection {
 		this.handle(lib.ModGetRequest, this.handleModGetRequest.bind(this));
 		this.handle(lib.ModListRequest, this.handleModListRequest.bind(this));
 		this.handle(lib.ModSearchRequest, this.handleModSearchRequest.bind(this));
+		this.handle(lib.ModPortalGetAllRequest, this.handleModPortalGetAllRequest.bind(this));
+		this.handle(lib.ModPortalDownloadRequest, this.handleModPortalDownloadRequest.bind(this));
+		this.handle(lib.ModDependencyResolveRequest, this.handleModDependencyResolveRequest.bind(this));
 		this.handle(lib.ModDeleteRequest, this.handleModDeleteRequest.bind(this));
 		this.handle(lib.LogSetSubscriptionsRequest, this.handleLogSetSubscriptionsRequest.bind(this));
 		this.handle(lib.LogQueryRequest, this.handleLogQueryRequest.bind(this));
@@ -116,6 +121,11 @@ export default class ControlConnection extends BaseConnection {
 		this.handle(lib.UserSetBannedRequest, this.handleUserSetBannedRequest.bind(this));
 		this.handle(lib.UserSetWhitelistedRequest, this.handleUserSetWhitelistedRequest.bind(this));
 		this.handle(lib.UserDeleteRequest, this.handleUserDeleteRequest.bind(this));
+		this.handle(lib.UserBulkImportRequest, this.handleUserBulkImportRequest.bind(this));
+		this.handle(lib.UserBulkExportRequest, this.handleUserBulkExportRequest.bind(this));
+		this.handle(lib.PluginListRequest, this.handlePluginListRequest.bind(this));
+		this.handle(lib.PluginUpdateRequest, this.handlePluginUpdateRequest.bind(this));
+		this.handle(lib.PluginInstallRequest, this.handlePluginInstallRequest.bind(this));
 		this.handle(lib.DebugDumpWsRequest, this.handleDebugDumpWsRequest.bind(this));
 	}

@@ -134,7 +144,7 @@ export default class ControlConnection extends BaseConnection {
 			this.checkPermission(message, entry);
 		} catch (err: any) {
 			this.connector.sendResponseError(new lib.ResponseError(err.message, err.code), message.src);
-			logger.audit(`Permission denied for ${message.name} by ${this.user.name} from ${this.connector.dst}`);
+			logger.audit(`Permission denied for ${message.name} by ${this.user.id} from ${this.connector.dst}`);
 			throw err;
 		}
 	}
@@ -195,7 +205,7 @@ export default class ControlConnection extends BaseConnection {
 	}

 	async handleHostRevokeTokensRequest(request: lib.HostRevokeTokensRequest) {
-		const host = this._controller.hosts.get(request.hostId);
+		const host = this._controller.hosts.getMutable(request.hostId);
 		if (!host) {
 			throw new Error(`Unknown host id (${request.hostId})`);
 		}
@@ -207,7 +217,7 @@ export default class ControlConnection extends BaseConnection {
 			hostConnection.connector.terminate();
 		}

-		this._controller.hostsUpdated([host]);
+		this._controller.hosts.set(host);
 	}

 	async handleHostListRequest(): Promise<lib.HostDetails[]> {
@@ -240,7 +250,7 @@ export default class ControlConnection extends BaseConnection {
 	}

 	async handleInstanceDetailsGetRequest(request: lib.InstanceDetailsGetRequest) {
-		return this._controller.getRequestInstance(request.instanceId).toInstanceDetails();
+		return this._controller.instances.getForRequest(request.instanceId).toInstanceDetails();
 	}

 	async handleInstanceDetailsListRequest() {
@@ -249,21 +259,29 @@ export default class ControlConnection extends BaseConnection {

 	async handleInstanceCreateRequest(request: lib.InstanceCreateRequest) {
 		const instanceConfig = new lib.InstanceConfig("controller");
+		if (request.cloneFromId) {
+			const baseInstance = this._controller.instances.get(request.cloneFromId);
+			if (!baseInstance) {
+				throw new lib.RequestError(`Instance with ID ${request.cloneFromId} does not exist`);
+			}
+			instanceConfig.update(baseInstance.config.toJSON(), false);
+			instanceConfig.set("instance.assigned_host", null); // New instances are unassigned
+		}
 		instanceConfig.update(request.config, false, "control");
-		await this._controller.instanceCreate(instanceConfig);
+		await this._controller.instances.createInstance(instanceConfig);
 	}

 	async handleInstanceDeleteRequest(request: lib.InstanceDeleteRequest) {
-		await this._controller.instanceDelete(request.instanceId);
+		await this._controller.instances.deleteInstance(request.instanceId);
 	}

 	async handleInstanceConfigGetRequest(request: lib.InstanceConfigGetRequest) {
-		let instance = this._controller.getRequestInstance(request.instanceId);
+		let instance = this._controller.instances.getForRequest(request.instanceId);
 		return instance.config.toRemote("control");
 	}

 	async handleInstanceConfigSetFieldRequest(request: lib.InstanceConfigSetFieldRequest) {
-		let instance = this._controller.getRequestInstance(request.instanceId);
+		let instance = this._controller.instances.getForRequest(request.instanceId);
 		if (request.field === "instance.assigned_host") {
 			throw new lib.RequestError("instance.assigned_host must be set through the assign-host interface");
 		}
@@ -278,14 +296,14 @@ export default class ControlConnection extends BaseConnection {
 	}

 	async handleInstanceConfigSetPropRequest(request: lib.InstanceConfigSetPropRequest) {
-		let instance = this._controller.getRequestInstance(request.instanceId);
+		let instance = this._controller.instances.getForRequest(request.instanceId);
 		let { field, prop, value } = request;
 		instance.config.setProp(field as keyof lib.InstanceConfigFields, prop, value, "control");
 		await this._controller.instanceConfigUpdated(instance);
 	}

 	async handleInstanceAssignRequest(request: lib.InstanceAssignRequest) {
-		await this._controller.instanceAssign(request.instanceId, request.hostId);
+		await this._controller.instances.assignInstance(request.instanceId, request.hostId ?? null);
 	}

 	async handleInstanceSaveDetailsListRequest() {
@@ -297,7 +315,7 @@ export default class ControlConnection extends BaseConnection {
 		let stream = await routes.createProxyStream(this._controller.app);
 		stream.filename = name;

-		let ready = new Promise((resolve, reject) => {
+		let ready = new Promise<void>((resolve, reject) => {
 			stream.events.on("source", resolve);
 			stream.events.on("timeout", () => reject(
 				new lib.RequestError("Timed out establishing stream from host")
@@ -319,8 +337,8 @@ export default class ControlConnection extends BaseConnection {
 		if (request.sourceInstanceId === request.targetInstanceId) {
 			throw new lib.RequestError("Source and target instance may not be the same");
 		}
-		let sourceInstance = this._controller.getRequestInstance(request.sourceInstanceId);
-		let targetInstance = this._controller.getRequestInstance(request.targetInstanceId);
+		let sourceInstance = this._controller.instances.getForRequest(request.sourceInstanceId);
+		let targetInstance = this._controller.instances.getForRequest(request.targetInstanceId);
 		let sourceHostId = sourceInstance.config.get("instance.assigned_host");
 		let targetHostId = targetInstance.config.get("instance.assigned_host");
 		if (sourceHostId === null) {
@@ -397,8 +415,7 @@ export default class ControlConnection extends BaseConnection {
 		if (this._controller.modPacks.has(modPack.id)) {
 			throw new lib.RequestError(`Mod pack with ID ${modPack.id} already exist`);
 		}
-		this._controller.modPacks.set(modPack.id, modPack);
-		this._controller.modPacksUpdated([modPack]);
+		this._controller.modPacks.set(modPack);
 	}

 	async handleModPackUpdateRequest(request: lib.ModPackUpdateRequest) {
@@ -406,19 +423,16 @@ export default class ControlConnection extends BaseConnection {
 		if (modPack.id === undefined || !this._controller.modPacks.has(modPack.id)) {
 			throw new lib.RequestError(`Mod pack with ID ${modPack.id} does not exist`);
 		}
-		this._controller.modPacks.set(modPack.id, modPack);
-		this._controller.modPacksUpdated([modPack]);
+		this._controller.modPacks.set(modPack);
 	}

 	async handleModPackDeleteRequest(request: lib.ModPackDeleteRequest) {
 		let { id } = request;
-		let modPack = this._controller.modPacks.get(id);
+		let modPack = this._controller.modPacks.getMutable(id);
 		if (!modPack) {
 			throw new lib.RequestError(`Mod pack with ID ${id} does not exist`);
 		}
-		modPack.isDeleted = true;
-		this._controller.modPacks.delete(id);
-		this._controller.modPacksUpdated([modPack]);
+		this._controller.modPacks.delete(modPack);
 	}

 	async handleModGetRequest(request: lib.ModGetRequest) {
@@ -518,6 +532,241 @@ export default class ControlConnection extends BaseConnection {
 		};
 	}

+	/**
+	 * Handle request to fetch all mods from the Factorio Mod Portal for a given version.
+	 * @param request - The request object containing factorioVersion.
+	 */
+	async handleModPortalGetAllRequest(request: lib.ModPortalGetAllRequest) {
+		const cacheKey = `${request.factorioVersion}-${request.hide_deprecated}`;
+		const cachedData = this._controller.modPortalCache.get(cacheKey);
+
+		const cacheDuration = this._controller.config.get("controller.mod_portal_cache_duration_minutes") * 60 * 1000;
+		if (cachedData && Date.now() - cachedData.timestamp < cacheDuration) {
+			return new lib.ModPortalGetAllRequest.Response(cachedData.data);
+		}
+
+		try {
+			logger.info(`Fetching mod portal data for ${cacheKey}`);
+			const mods = await lib.ModStore.fetchAllModsFromPortal(
+				request.factorioVersion,
+				this._controller.config.get("controller.mod_portal_page_size"),
+				request.hide_deprecated
+			);
+			this._controller.modPortalCache.set(cacheKey, { timestamp: Date.now(), data: mods });
+			// The Response class is defined inline within the Request class
+			return new lib.ModPortalGetAllRequest.Response(mods);
+		} catch (error: any) {
+			logger.error(`Error fetching all mods from portal (${request.factorioVersion}): ${error}`);
+			// Propagate a user-friendly error back to the client
+			throw new lib.RequestError(`Portal mod fetch failed: ${error}`);
+		}
+	}
+
+	/**
+	 * Handle request to download a mod from the Factorio Mod Portal to the controller.
+	 * @param request - Request object with mod name, version, and factorioVersion.
+	 */
+	async handleModPortalDownloadRequest(request: lib.ModPortalDownloadRequest) {
+		const factorioVersion = request.factorioVersion;
+		const toDownload = this._controller.modStore.filterInstalled(request.mods, false);
+
+		if (toDownload.length > 0) {
+			// Get Factorio credentials from config
+			const username = this._controller.config.get("controller.factorio_username");
+			const token = this._controller.config.get("controller.factorio_token");
+
+			if (!username || username === "" || !token || token === "") {
+				throw new lib.RequestError("Factorio credentials (username, token) not configured on the controller.");
+			}
+
+			try {
+				logger.info(`Downloading ${toDownload.length} mods for Factorio ${factorioVersion} from portal.`);
+				await this._controller.modStore.downloadMods(toDownload, username, token, factorioVersion);
+
+			} catch (error: any) {
+				logger.error(`Error downloading mods from portal: ${error.message}`);
+				// Improve error message clarity
+				let errorMessage = "Mod portal download failed";
+				if (error instanceof lib.RequestError) {
+					errorMessage += `: ${error.message}`;
+				} else if (error.message.includes("401") || error.message.includes("Unauthorized")) {
+					errorMessage += ": Authentication failed. Check Factorio username/token in controller config.";
+				} else if (error.message.includes("404") || error.message.includes("Not Found")) {
+					errorMessage += ": Mod version not found on the portal.";
+				} else {
+					errorMessage += `: ${error.message}`;
+				}
+				throw new lib.RequestError(errorMessage);
+			}
+		}
+
+		// Verify all mods are present
+		const modInfos = [];
+		const installedMods = [...this._controller.modStore.mods()];
+		for (const mod of request.mods) {
+			const modInfo = installedMods.find(m => m.name === mod.name && mod.version.testVersion(m.version));
+			if (!modInfo) {
+				throw new lib.RequestError(`Failed to find mod ${mod.name} in store after download attempt.`);
+			}
+			modInfos.push(modInfo);
+		}
+
+		return modInfos;
+	}
+
+	// eslint-disable-next-line complexity
+	async handleModDependencyResolveRequest(request: lib.ModDependencyResolveRequest) {
+		const {factorioVersion, checkForUpdates} = request;
+		const searchQueue = [...request.mods];
+		const localInfos = [...this._controller.modStore.mods()];
+
+		const builtInModNames = lib.ModPack.getBuiltinModNames(factorioVersion);
+		const skipSearch = new Set(builtInModNames);
+
+		type ModPortalModType = InstanceType<typeof lib.ModPortalGetAllRequest.Response>["mods"][number];
+		type ModPortalReleaseType = NonNullable<ModPortalModType["releases"]>[number];
+		const dependencyRequirements = new Map<string, lib.ModVersionRange>();
+		const optionalRequirements = new Map<string, lib.ModVersionRange>();
+		const candidateReleases = new Map<string, lib.ModInfo>();
+		const errors = new Map<string, lib.ModDependencyResolveErrors>();
+
+		const _modPortalReleases = new Map<string, ModPortalModType | null>();
+		async function fetchModReleases(modName: string) {
+			let releases = _modPortalReleases.get(modName);
+			if (releases === undefined) {
+				try {
+					releases = await lib.ModStore.fetchModReleases(modName);
+				} catch (error: any) {
+					if (!error.message.includes("404") && !error.message.includes("Not Found")) {
+						logger.error(`Error fetching mod from portal: ${error.message}`);
+						throw new lib.RequestError(`Dependency resolution failed: ${error.message}`);
+					} else {
+						releases = null;
+					}
+				}
+			}
+			_modPortalReleases.set(modName, releases);
+			return releases;
+		}
+
+		function selectModRelease(releases: ModPortalModType | null, versionRange: lib.ModVersionRange) {
+			if (!releases || !releases.releases) {
+				return null;
+			}
+
+			// Select the latest matching version
+			const release = releases.releases
+				.filter(info => versionRange.testVersion(info.version))
+				.reduce<ModPortalReleaseType | undefined>((max, cur) => (
+					max && lib.integerFullVersion(max.version) > lib.integerFullVersion(cur.version) ? max : cur
+				), undefined);
+
+			if (!release) {
+				return null;
+			}
+
+			// Create the mod info class from the selected
+			try {
+				return lib.ModInfo.fromJSON({
+					...release.info_json, // includes dependencies
+					sha1: release.sha1,
+					version: release.version,
+					name: releases.name,
+					author: releases.owner,
+					title: releases.title,
+				});
+			} catch {
+				// Can error if there are invalid dependencies
+				errors.set(releases.name, "invalidDependency");
+				return null;
+			}
+		}
+
+		while (searchQueue.length > 0) {
+			// Dequeue the next mod, skip if incompatible
+			const mod = searchQueue.shift()!;
+			if (mod.incompatible) {
+				errors.set(mod.name, "incompatible");
+				continue;
+			}
+
+			// Get the current version range (optionals are tracked in case they become required)
+			let versionRange = dependencyRequirements.get(mod.name);
+			if (!versionRange) {
+				versionRange = optionalRequirements.get(mod.name) ?? new lib.ModVersionRange();
+				if (mod.required) {
+					dependencyRequirements.set(mod.name, versionRange);
+					optionalRequirements.delete(mod.name);
+				} else {
+					optionalRequirements.set(mod.name, versionRange);
+				}
+			}
+
+			// Update the version range if needed
+			if (mod.version) {
+				versionRange.combineVersion(mod.version);
+				if (!versionRange.valid) {
+					candidateReleases.delete(mod.name);
+					errors.set(mod.name, "unsatisfiable");
+				}
+			}
+
+			// Do not add dependencies for errors, skips, optionals, or valid candidates
+			const existingCandidate = candidateReleases.get(mod.name);
+			if (errors.has(mod.name) || skipSearch.has(mod.name) || optionalRequirements.has(mod.name) || (
+				existingCandidate && versionRange.testVersion(existingCandidate.version)
+			)) {
+				continue;
+			}
+
+			// Check if a local version fits the requirements
+			let candidate = localInfos
+				.filter(info => (info.name === mod.name && versionRange.testVersion(info.version)))
+				.reduce<lib.ModInfo | undefined>((max, cur) => (
+					max && max.integerVersion > cur.integerVersion ? max : cur
+				), undefined);
+
+			// Check if a mod poral version fits the requirements
+			if (!candidate || checkForUpdates) {
+				const releases = await fetchModReleases(mod.name);
+				const release = selectModRelease(releases, versionRange);
+				// We only select the mod portal release if it is more recent than the local candidate
+				if (release && (!candidate || release.integerVersion > candidate.integerVersion)) {
+					candidate = release;
+				}
+			}
+
+			// Queue the dependencies of the new candidate
+			if (candidate) {
+				candidateReleases.set(mod.name, candidate);
+				for (const dep of candidate.dependencies) {
+					searchQueue.push(dep);
+				}
+			} else {
+				candidateReleases.delete(mod.name);
+				skipSearch.add(mod.name);
+			}
+		}
+
+		// Add the not found dependencies as errors
+		for (const modName of dependencyRequirements.keys()) {
+			if (!candidateReleases.has(modName) && !errors.has(modName)) {
+				errors.set(modName, "notFound");
+			}
+		}
+
+		// Remove incompatible dependencies if they aren't required by others
+		for (const [modName, error] of errors) {
+			if (error === "incompatible" && !dependencyRequirements.has(modName)) {
+				errors.delete(modName);
+			}
+		}
+
+		return new lib.ModDependencyResolveRequest.Response(
+			[...candidateReleases.values()], errors,
+		);
+	}
+
 	async handleModDeleteRequest(request: lib.ModDeleteRequest) {
 		await this._controller.modStore.deleteMod(request.name, request.version);
 	}
@@ -577,22 +826,21 @@ export default class ControlConnection extends BaseConnection {
 	}

 	async handleRoleListRequest() {
-		return [...this._controller.userManager.roles.values()];
+		return [...this._controller.roles.values()];
 	}

 	async handleRoleCreateRequest(request: lib.RoleCreateRequest) {
-		let lastId = Math.max.apply(null, [...this._controller.userManager.roles.keys()]);
+		let lastId = Math.max.apply(null, [...this._controller.roles.keys()]);

 		// Start at 5 to leave space for future default roles
 		let id = Math.max(5, lastId+1);
-		this._controller.userManager.roles.set(id, lib.Role.fromJSON({ id, ...request }));
-		this._controller.userManager.dirty = true;
+		this._controller.roles.set(lib.Role.fromJSON({ id, ...request }));
 		return id;
 	}

 	async handleRoleUpdateRequest(request: lib.RoleUpdateRequest) {
 		let { id, name, description, permissions } = request;
-		let role = this._controller.userManager.roles.get(id);
+		let role = this._controller.roles.getMutable(id);
 		if (!role) {
 			throw new lib.RequestError(`Role with ID ${id} does not exist`);
 		}
@@ -600,112 +848,109 @@ export default class ControlConnection extends BaseConnection {
 		role.name = name;
 		role.description = description;
 		role.permissions = new Set(permissions);
-		this._controller.rolePermissionsUpdated(role);
+		this._controller.roles.set(role);
 	}

 	async handleRoleGrantDefaultPermissionsRequest(request: lib.RoleGrantDefaultPermissionsRequest) {
-		let role = this._controller.userManager.roles.get(request.id);
+		let role = this._controller.roles.get(request.id);
 		if (!role) {
 			throw new lib.RequestError(`Role with ID ${request.id} does not exist`);
 		}

 		role.grantDefaultPermissions();
-		this._controller.rolePermissionsUpdated(role);
+		this._controller.roles.set(role);
 	}

 	async handleRoleDeleteRequest(request: lib.RoleDeleteRequest) {
 		let id = request.id;

-		if (!this._controller.userManager.roles.delete(id)) {
+		const role = this._controller.roles.get(id);
+		if (!role) {
 			throw new lib.RequestError(`Role with ID ${id} does not exist`);
 		}
-		this._controller.userManager.dirty = true;
+		this._controller.roles.delete(role);

-		for (let user of this._controller.userManager.users.values()) {
-			if (user.roleIds.delete(id)) {
+		for (const user of this._controller.users.values()) {
+			if (user.removeRole(id)) {
 				this._controller.userPermissionsUpdated(user);
 			}
 		}
 	}

-	async handleUserGetRequest(request: lib.UserGetRequest): Promise<lib.User> {
+	async handleUserGetRequest(request: lib.UserGetRequest): Promise<lib.UserDetails> {
 		let name = request.name;
-		let user = this._controller.userManager.users.get(name);
+		let user = this._controller.users.getByName(name);
 		if (!user) {
 			throw new lib.RequestError(`User ${name} does not exist`);
 		}

-		return user;
+		return user.toUserDetails();
 	}

-	async handleUserListRequest(): Promise<lib.User[]> {
-		return [...this._controller.userManager.users.values()];
+	async handleUserListRequest(): Promise<lib.UserDetails[]> {
+		return [...this._controller.users.records.values()].map(user => user.toUserDetails());
 	}

 	async handleUserCreateRequest(request: lib.UserCreateRequest) {
-		let user = this._controller.userManager.createUser(request.name);
-		this._controller.usersUpdated([user]);
+		this._controller.users.createUser(request.name);
 	}

 	async handleUserRevokeTokenRequest(request: lib.UserRevokeTokenRequest) {
-		let user = this._controller.userManager.users.get(request.name);
+		let user = this._controller.users.getByName(request.name);
 		if (!user) {
 			throw new lib.RequestError(`User '${request.name}' does not exist`);
 		}
-		if (user.name !== this.user.name) {
+		if (user.id !== this.user.id) {
 			this.user.checkPermission("core.user.revoke_other_token");
 		}

 		user.invalidateToken();
 		for (let controlConnection of this._controller.wsServer.controlConnections.values()) {
-			if (controlConnection.user.name === user.name) {
+			if (controlConnection.user.id === user.id) {
 				controlConnection.connector.terminate();
 			}
 		}
-		this._controller.usersUpdated([user]);
 	}

 	async handleUserUpdateRolesRequest(request: lib.UserUpdateRolesRequest) {
-		let user = this._controller.userManager.users.get(request.name);
+		let user = this._controller.users.getByName(request.name);
 		if (!user) {
 			throw new lib.RequestError(`User '${request.name}' does not exist`);
 		}

 		for (let roleId of request.roles) {
-			if (!this._controller.userManager.roles.has(roleId)) {
+			if (!this._controller.roles.has(roleId)) {
 				throw new lib.RequestError(`Role with ID ${roleId} does not exist`);
 			}
 		}

-		user.roleIds = new Set(request.roles);
+		user.set("roleIds", new Set(request.roles));
 		this._controller.userPermissionsUpdated(user);
-		this._controller.usersUpdated([user]);
 	}

 	async handleUserSetAdminRequest(request: lib.UserSetAdminRequest) {
 		let { name, create, admin } = request;
-		let user = this._controller.userManager.users.get(name);
+		let user = this._controller.users.getByName(name);
 		if (!user) {
 			if (create) {
 				this.user.checkPermission("core.user.create");
-				user = this._controller.userManager.createUser(name);
+				user = this._controller.users.createUser(name);
 			} else {
 				throw new lib.RequestError(`User '${name}' does not exist`);
 			}
 		}

-		user.isAdmin = admin;
-		this._controller.usersUpdated([user]);
+		user.set("isAdmin", admin);
 		this._controller.sendTo("allInstances", new lib.InstanceAdminlistUpdateEvent(name, admin));
 	}

 	async handleUserSetBannedRequest(request: lib.UserSetBannedRequest) {
 		let { name, create, banned, reason } = request;
-		let user = this._controller.userManager.users.get(name);
+		let user = this._controller.users.getByNameMutable(name);
 		if (!user) {
 			if (create) {
 				this.user.checkPermission("core.user.create");
-				user = this._controller.userManager.createUser(name);
+				user = this._controller.users.createUser(name);
 			} else {
 				throw new lib.RequestError(`User '${name}' does not exist`);
 			}
@@ -713,37 +958,34 @@ export default class ControlConnection extends BaseConnection {

 		user.isBanned = banned;
 		user.banReason = reason;
-		this._controller.usersUpdated([user]);
+		user.saveRecord();
 		this._controller.sendTo("allInstances", new lib.InstanceBanlistUpdateEvent(name, banned, reason));
 	}

 	async handleUserSetWhitelistedRequest(request: lib.UserSetWhitelistedRequest) {
 		let { name, create, whitelisted } = request;
-		let user = this._controller.userManager.users.get(name);
+		let user = this._controller.users.getByName(name);
 		if (!user) {
 			if (create) {
 				this.user.checkPermission("core.user.create");
-				user = this._controller.userManager.createUser(name);
+				user = this._controller.users.createUser(name);
 			} else {
 				throw new lib.RequestError(`User '${name}' does not exist`);
 			}
 		}

-		user.isWhitelisted = whitelisted;
-		this._controller.usersUpdated([user]);
+		user.set("isWhitelisted", whitelisted);
 		this._controller.sendTo("allInstances", new lib.InstanceWhitelistUpdateEvent(name, whitelisted));
 	}

 	async handleUserDeleteRequest(request: lib.UserDeleteRequest) {
 		let name = request.name;
-		let user = this._controller.userManager.users.get(name);
+		let user = this._controller.users.getByName(name);
 		if (!user) {
 			throw new lib.RequestError(`User '${name}' does not exist`);
 		}

-		user.isDeleted = true;
-		this._controller.userManager.users.delete(name);
-		this._controller.usersUpdated([user]);
+		this._controller.users.deleteUser(user);

 		if (user.isAdmin) {
 			this._controller.sendTo("allInstances", new lib.InstanceAdminlistUpdateEvent(name, false));
@@ -756,6 +998,238 @@ export default class ControlConnection extends BaseConnection {
 		}
 	}

+	/** This does not do a full restore, rather it demotes / unbanns / unwhitelistes users */
+	async handleUserBulkRestoreRequest(request: lib.UserBulkImportRequest, updated: Map<string, UserRecord>) {
+		if (request.importType === "users") {
+			// Update all fields for all users
+			const users = request.users as Extract<typeof request.users, { username: string }[]>;
+			const admin = new Set(users.filter(u => u.is_admin).map(u => u.username.toLowerCase()));
+			const banned = new Set(users.filter(u => u.is_banned).map(u => u.username.toLowerCase()));
+			const whitelist = new Set(users.filter(u => u.is_whitelisted).map(u => u.username.toLowerCase()));
+			for (const user of this._controller.users.valuesMutable()) {
+				if (user.isAdmin && !admin.has(user.name)) {
+					user.isAdmin = false;
+					updated.set(user.id, user);
+				}
+				if (user.isBanned && !banned.has(user.name)) {
+					user.isBanned = false;
+					user.banReason = "";
+					updated.set(user.id, user);
+				}
+				if (user.isWhitelisted && !whitelist.has(user.name)) {
+					user.isWhitelisted = false;
+					updated.set(user.id, user);
+				}
+			}
+		} else if (request.importType === "bans") {
+			// Bans have extra logic to handle ban reason
+			const users = request.users as (string | { username: string, reason: string })[];
+			const expected = new Set(
+				users.map(u => (typeof u === "string" ? u.toLowerCase() : u.username.toLowerCase()))
+			);
+			for (const user of this._controller.users.valuesMutable()) {
+				if (user.isBanned && !expected.has(user.name)) {
+					user.isBanned = false;
+					user.banReason = "";
+					updated.set(user.id, user);
+				}
+			}
+		} else {
+			// Whitelist and admin have the same logic
+			const users = request.users as string[];
+			const expected = new Set(users.map(u => u.toLowerCase()));
+			const prop = request.importType === "admins" ? "isAdmin" : "isWhitelisted";
+			for (const user of this._controller.users.valuesMutable()) {
+				if (user[prop] && !expected.has(user.name)) {
+					user[prop] = false;
+					updated.set(user.id, user);
+				}
+			}
+		}
+	}
+
+	async handleUserBulkImportRequest(request: lib.UserBulkImportRequest) {
+		let backup: undefined | Awaited<ReturnType<ControlConnection["handleUserBulkExportRequest"]>>;
+		const updated = new Map<User["id"], User>();
+		if (request.restore) {
+			// Unban / Demote / Unwhitelist players not on the list
+			backup = await this.handleUserBulkExportRequest(new lib.UserBulkExportRequest(request.importType));
+			await this.handleUserBulkRestoreRequest(request, updated);
+		}
+
+		// Will get a user or attempt to create one
+		// UserManager.getOrCreateUser not used due to inclusion of checkPermission
+		const getUserOrCreate = (username: string) => {
+			const user = this._controller.users.getByNameMutable(username);
+			if (user) { return updated.get(user.id) ?? user; }
+			this.user.checkPermission("core.user.create");
+			return this._controller.users.createUser(username);
+		};
+
+		// Merge the imported data with existing data, this is strictly additive
+		if (request.importType === "users") {
+			// Update all fields
+			const users = request.users as Extract<typeof request.users, { username: string }[]>;
+			for (const user of users) {
+				const cUser = getUserOrCreate(user.username);
+				if (user.is_admin && !cUser.isAdmin) {
+					cUser.isAdmin = true;
+					updated.set(cUser.id, cUser);
+				}
+				if (user.is_banned && !cUser.isBanned) {
+					cUser.isBanned = true;
+					cUser.banReason = user.ban_reason ?? "";
+					updated.set(cUser.id, cUser);
+				}
+				if (user.is_whitelisted && !cUser.isWhitelisted) {
+					cUser.isWhitelisted = true;
+					updated.set(cUser.id, cUser);
+				}
+			}
+		} else if (request.importType === "bans") {
+			// Bans have extra logic to handle ban reason
+			const users = request.users as (string | { username: string, reason: string })[];
+			for (const user of users) {
+				if (typeof user === "string") {
+					const cUser = getUserOrCreate(user);
+					if (!cUser.isBanned) {
+						cUser.isBanned = true;
+						cUser.banReason = "";
+						updated.set(cUser.id, cUser);
+					}
+				} else {
+					const cUser = getUserOrCreate(user.username);
+					if (!cUser.isBanned) {
+						cUser.isBanned = true;
+						cUser.banReason = user.reason;
+						updated.set(cUser.id, cUser);
+					}
+				}
+			}
+		} else {
+			// Whitelist and admin have the same logic
+			const users = request.users as string[];
+			const prop = request.importType === "admins" ? "isAdmin" : "isWhitelisted";
+			for (const user of users) {
+				const cUser = getUserOrCreate(user);
+				if (!cUser[prop]) {
+					cUser[prop] = true;
+					updated.set(cUser.id, cUser);
+				}
+			}
+		}
+
+		// Send the necessary update events
+		const updatedUsers = [...updated.values()];
+		this._controller.users.records.setMany(updatedUsers);
+
+		// Resync the host user lists
+		const adminlist: Set<string> = new Set();
+		const banlist: Map<string, string> = new Map();
+		const whitelist: Set<string> = new Set();
+
+		for (let user of this._controller.users.values()) {
+			if (user.isAdmin) {
+				adminlist.add(user.id);
+			}
+			if (user.isBanned) {
+				banlist.set(user.id, user.banReason);
+			}
+			if (user.isWhitelisted) {
+				whitelist.add(user.id);
+			}
+		}
+
+		this._controller.sendEvent(
+			new lib.SyncUserListsEvent(adminlist, banlist, whitelist),
+			lib.Address.fromShorthand("allHosts")
+		);
+
+		return backup ?? [];
+	}
+
+	async handleUserBulkExportRequest(request: lib.UserBulkExportRequest) {
+		if (request.exportType === "users") {
+			// Send a full user export
+			const usersToSend = [] as lib.ClusterioUserExport["users"];
+			for (const user of this._controller.users.values()) {
+				let send = false;
+				const userToSend = { username: user.name } as typeof usersToSend[0];
+				if (user.isBanned) {
+					send = true;
+					userToSend.is_banned = true;
+					if (user.banReason !== "") {
+						userToSend.ban_reason = user.banReason;
+					}
+				}
+				if (user.isAdmin) {
+					send = true;
+					userToSend.is_admin = true;
+				}
+				if (user.isWhitelisted) {
+					send = true;
+					userToSend.is_whitelisted = true;
+				}
+				if (send) {
+					usersToSend.push(userToSend);
+				}
+			}
+			return new lib.ClusterioUserExport(usersToSend);
+		} else if (request.exportType === "bans") {
+			// Bans have extra logic to handle ban reason
+			const usersToSend = [] as Array<string | { username: string, reason: string }>;
+			for (const user of this._controller.users.values()) {
+				if (user.isBanned) {
+					if (user.banReason && user.banReason !== "") {
+						usersToSend.push({ username: user.name, reason: user.banReason });
+					} else {
+						usersToSend.push(user.name);
+					}
+				}
+			}
+			return usersToSend;
+		}
+
+		// This is a whitelist or admins export
+		const usersToSend = [] as string[];
+		const prop = request.exportType === "admins" ? "isAdmin" : "isWhitelisted";
+		for (const user of this._controller.users.values()) {
+			if (user[prop]) {
+				usersToSend.push(user.name);
+			}
+		}
+		return usersToSend;
+	}
+
+	async handleControllerUpdateRequest(request: lib.ControllerUpdateRequest) {
+		if (!this._controller.config.get("controller.allow_remote_updates")) {
+			throw new lib.RequestError("Remote updates are disabled on this machine");
+		}
+		return await lib.updatePackage("@clusterio/controller");
+	}
+
+	async handlePluginUpdateRequest(request: lib.PluginUpdateRequest) {
+		if (!this._controller.config.get("controller.allow_plugin_updates")) {
+			throw new lib.RequestError("Plugin updates are disabled on this machine");
+		}
+		return await lib.handlePluginUpdate(request.pluginPackage, this._controller.pluginInfos);
+	}
+
+	async handlePluginInstallRequest(request: lib.PluginInstallRequest) {
+		if (!this._controller.config.get("controller.allow_plugin_install")) {
+			throw new lib.RequestError("Plugin installs are disabled on this machine");
+		}
+		return await lib.handlePluginInstall(request.pluginPackage);
+	}
+
+	async handlePluginListRequest(request: lib.PluginListRequest) {
+		return this._controller.pluginInfos.map(pluginInfo => lib.PluginDetails.fromNodeEnvInfo(
+			pluginInfo,
+			this._controller.plugins.has(pluginInfo.name),
+			this._controller.config.get(`${pluginInfo.name}.load_plugin`),
+		));
+	}
+
 	async handleDebugDumpWsRequest(request: lib.DebugDumpWsRequest) {
 		this.ws_dumper = data => {
 			if (this.connector.connected) {
@@ -1,93 +0,0 @@
-import { Static, Type } from "@sinclair/typebox";
-import { IControllerUser, PermissionError, PlayerStats, Role, User, permissions } from "@clusterio/lib";
-import type UserManager from "./UserManager";
-
-export default class ControllerUser extends User implements IControllerUser {
-	constructor(
-		public userManager: UserManager,
-		/** Unix time in seconds the user token must be issued after to be valid.  */
-		public tokenValidAfter = 0,
-		...args: ConstructorParameters<typeof User>
-	) {
-		super(...args);
-	}
-
-	static jsonSchema = Type.Object({
-		...User.jsonSchema.properties,
-		token_valid_after: Type.Optional(Type.Number()),
-	});
-
-	static fromJSON(json: Static<typeof this.jsonSchema>, userManager: UserManager) {
-		const roleIds = new Set<number>(json.roles ?? []);
-		const instanceStats = new Map(
-			(json.instance_stats ?? []).map(
-				([id, stats]) => [id, PlayerStats.fromJSON(stats)]
-			)
-		);
-		const playerStats = User._calculatePlayerStats(instanceStats);
-		return new this(
-			userManager,
-			json.token_valid_after,
-			json.name,
-			roleIds,
-			new Set(json.instances),
-			json.is_admin,
-			json.is_banned,
-			json.is_whitelisted,
-			json.ban_reason,
-			json.updated_at_ms,
-			json.is_deleted,
-			playerStats,
-			instanceStats,
-		);
-	}
-
-	toJSON(controller?: boolean): Static<typeof ControllerUser.jsonSchema> {
-		if (!controller) {
-			return super.toJSON();
-		}
-
-		const json: Static<typeof ControllerUser.jsonSchema> = super.toJSON();
-		if (this.tokenValidAfter) {
-			json.token_valid_after = this.tokenValidAfter;
-		}
-
-		return json;
-	}
-
-	get roles(): ReadonlySet<Readonly<Role>> {
-		return new Set([...this.roleIds].map(
-			id => this.userManager.roles.get(id)
-		).filter(
-			(r): r is Role => Boolean(r)
-		));
-	}
-
-	/**
-	 * Invalidate current tokens for the user
-	 *
-	 * Sets the tokenValidAfter property to the current time, which causes
-	 * all currently issued tokens for the user to become invalid.
-	 */
-	invalidateToken() {
-		this.tokenValidAfter = Math.floor(Date.now() / 1000);
-	}
-
-	checkPermission(permission: string) {
-		if (!permissions.has(permission)) {
-			throw new Error(`permission ${permission} does not exist`);
-		}
-
-		for (let roleId of this.roleIds) {
-			let role = this.userManager.roles.get(roleId);
-			if (!role) {
-				continue;
-			}
-			if (role.permissions.has("core.admin") || role.permissions.has(permission)) {
-				return;
-			}
-		}
-
-		throw new PermissionError("Permission denied");
-	}
-}
@@ -5,8 +5,8 @@ import * as lib from "@clusterio/lib";
 const { logger } = lib;

 import BaseConnection from "./BaseConnection";
-import InstanceInfo from "./InstanceInfo";
-import HostInfo from "./HostInfo";
+import InstanceRecord from "./InstanceRecord";
+import HostRecord from "./HostRecord";


 /**
@@ -16,7 +16,7 @@ import HostInfo from "./HostInfo";
 * @alias module:controller/src/HostConnection
 */
 export default class HostConnection extends BaseConnection {
-	private info: HostInfo;
+	private info: HostRecord;
 	plugins: Map<string, string>;

 	constructor(
@@ -30,7 +30,7 @@ export default class HostConnection extends BaseConnection {
 		this.plugins = new Map(Object.entries(registerData.plugins));

 		const previousHostInfo = this._controller.hosts.get(registerData.id);
-		this.info = new HostInfo(
+		this.info = new HostRecord(
 			registerData.id,
 			previousHostInfo?.name ?? "",
 			registerData.version,
@@ -42,13 +42,12 @@ export default class HostConnection extends BaseConnection {
 			0,
 			false,
 		);
-		this._controller.hosts.set(this.id, this.info);
-		this._controller.hostsUpdated([this.info]);
+		this._controller.hosts.set(this.info);

 		this._checkPluginVersions();

 		for (let event of ["connect", "drop", "resume", "close"] as const) {
-			// eslint-disable-next-line no-loop-func
+
 			this.connector.on(event, () => {
 				for (let plugin of this._controller.plugins.values()) {
 					plugin.onHostConnectionEvent(this, event);
@@ -57,10 +56,9 @@ export default class HostConnection extends BaseConnection {
 		}

 		this.connector.on("close", () => {
-			const now = Date.now();
 			// Update status to unknown for instances on this host.
-			const instances: InstanceInfo[] = [];
-			for (let instance of this._controller.instances.values()) {
+			const instances: InstanceRecord[] = [];
+			for (let instance of this._controller.instances.valuesMutable()) {
 				if (instance.config.get("instance.assigned_host") !== this.id) {
 					continue;
 				}
@@ -68,21 +66,24 @@ export default class HostConnection extends BaseConnection {
 				instances.push(instance);
 				let prev = instance.status;
 				instance.status = "unknown";
-				instance.updatedAtMs = now;
 				lib.invokeHook(this._controller.plugins, "onInstanceStatusChanged", instance, prev);
 			}
-			this._controller.instanceDetailsUpdated(instances);
+			this._controller.instances.records.setMany(instances);

 			this.info.connected = false;
-			this._controller.hostsUpdated([this.info]);
+			this._controller.hosts.set(this.info);
 		});

+		this.handle(lib.GetFactorioCredentialsRequest, this.handleGetFactorioCredentialsRequest.bind(this));
 		this.handle(lib.HostInfoUpdateEvent, this.handleHostInfoUpdateEvent.bind(this));
 		this.handle(lib.InstanceStatusChangedEvent, this.handleInstanceStatusChangedEvent.bind(this));
 		this.handle(lib.InstancesUpdateRequest, this.handleInstancesUpdateRequest.bind(this));
 		this.handle(lib.InstanceSaveDetailsUpdatesEvent, this.handleInstanceSaveDetailsUpdatesEvent.bind(this));
 		this.handle(lib.LogMessageEvent, this.handleLogMessageEvent.bind(this));
 		this.handle(lib.InstancePlayerUpdateEvent, this.handleInstancePlayerUpdateEvent.bind(this));
+		this.snoopEvent(lib.InstanceAdminlistUpdateEvent, this.snoopInstanceAdminlistUpdateEvent.bind(this));
+		this.snoopEvent(lib.InstanceBanlistUpdateEvent, this.snoopInstanceBanlistUpdateEvent.bind(this));
+		this.snoopEvent(lib.InstanceWhitelistUpdateEvent, this.snoopInstanceWhitelistUpdateEvent.bind(this));
 	}

 	validateIngress(message: lib.MessageRoutable) {
@@ -155,14 +156,33 @@ export default class HostConnection extends BaseConnection {
 		return this.info.id;
 	}

+	/**
+	 * Remote address of the host this connection is connected to
+	 *
+	 * @returns {string} host remote address.
+	 */
+	get remoteAddress() {
+		return this.info.remoteAddress;
+	}
+
+	async handleGetFactorioCredentialsRequest() {
+		if (this._controller.config.get("controller.share_factorio_credentials_with_hosts")) {
+			return {
+				username: this._controller.config.get("controller.factorio_username") ?? undefined,
+				token: this._controller.config.get("controller.factorio_token") ?? undefined,
+			};
+		}
+		return {};
+	}
+
 	async handleHostInfoUpdateEvent(event: lib.HostInfoUpdateEvent) {
 		this.info.name = event.update.name;
 		this.info.publicAddress = event.update.publicAddress;
-		this._controller.hostsUpdated([this.info]);
+		this._controller.hosts.set(this.info);
 	}

 	async handleInstanceStatusChangedEvent(request: lib.InstanceStatusChangedEvent) {
-		let instance = this._controller.instances.get(request.instanceId);
+		let instance = this._controller.instances.getMutable(request.instanceId);

 		// It's possible to get updates from an instance that does not exist
 		// or is not assigned to the host it originated from if it was
@@ -187,10 +207,15 @@ export default class HostConnection extends BaseConnection {

 		let prev = instance.status;
 		instance.status = request.status;
+		// If the instance has transitioned to running then updated the started at time
+		if (request.status === "running" && prev === "starting") {
+			instance.startedAtMs = Date.now();
+		}
+
 		instance.gamePort = request.gamePort;
-		instance.updatedAtMs = Date.now();
+		instance.factorioVersion = request.factorioVersion;
+		this._controller.instances.records.set(instance);
 		logger.verbose(`Instance ${instance.config.get("instance.name")} State: ${instance.status}`);
-		this._controller.instanceDetailsUpdated([instance]);
 		await lib.invokeHook(this._controller.plugins, "onInstanceStatusChanged", instance, prev);
 	}

@@ -205,12 +230,12 @@ export default class HostConnection extends BaseConnection {
 		}

 		// Assign instances the host has but controller does not
-		const instanceUpdates: InstanceInfo[] = [];
+		const instanceUpdates: InstanceRecord[] = [];
 		for (let instanceData of request.instances) {
 			const instanceConfig = new lib.InstanceConfig("controller");
 			instanceConfig.update(instanceData.config, false, "host");

-			let controllerInstance = this._controller.instances.get(instanceConfig.get("instance.id"));
+			let controllerInstance = this._controller.instances.getMutable(instanceConfig.get("instance.id"));
 			if (controllerInstance) {
 				// Check if this instance is assigned somewhere else.
 				if (controllerInstance.config.get("instance.assigned_host") !== this.id) {
@@ -225,9 +250,12 @@ export default class HostConnection extends BaseConnection {
 					let prev = controllerInstance.status;
 					controllerInstance.status = instanceData.status;
 					controllerInstance.gamePort = instanceData.gamePort;
-					controllerInstance.updatedAtMs = Date.now();
-					logger.verbose(`Instance ${instanceConfig.get("instance.name")} State: ${instanceData.status}`);
+					controllerInstance.factorioVersion = instanceData.factorioVersion;
+					if (instanceData.status === "running" && prev === "starting") {
+						controllerInstance.startedAtMs = Date.now();
+					}
 					instanceUpdates.push(controllerInstance);
+					logger.verbose(`Instance ${instanceConfig.get("instance.name")} State: ${instanceData.status}`);
 					await lib.invokeHook(
 						this._controller.plugins, "onInstanceStatusChanged", controllerInstance, prev
 					);
@@ -236,42 +264,38 @@ export default class HostConnection extends BaseConnection {
 			}

 			instanceConfig.set("instance.assigned_host", this.id);
-			let newInstance = new InstanceInfo(
-				instanceConfig,
-				instanceData.status,
-				instanceData.gamePort,
-				Date.now(),
-			);
-			this._controller.instances.set(instanceConfig.get("instance.id"), newInstance);
-			this._controller.instancesDirty = true;
-			this._controller.addInstanceHooks(newInstance);
-			await this.send(
-				new lib.InstanceAssignInternalRequest(
-					instanceConfig.get("instance.id"), instanceConfig.toRemote("host")
-				)
-			);
+			const newInstance = await this._controller.instances.createInstance(instanceConfig, true);
+			newInstance.factorioVersion = instanceData.factorioVersion;
+			newInstance.gamePort = instanceData.gamePort;
+			newInstance.status = instanceData.status;
 			instanceUpdates.push(newInstance);
-			await lib.invokeHook(this._controller.plugins, "onInstanceStatusChanged", newInstance);
 		}

-		if (instanceUpdates.length) {
-			this._controller.instanceDetailsUpdated(instanceUpdates);
-		}
+		// We suppress the changes made by createInstance so we must manually make them here
+		this._controller.instances.records.setMany(instanceUpdates);
+		await Promise.all(instanceUpdates.flatMap(newInstance => [
+			lib.invokeHook(this._controller.plugins, "onInstanceStatusChanged", newInstance),
+			this.send(
+				new lib.InstanceAssignInternalRequest(
+					newInstance.config.get("instance.id"), newInstance.config.toRemote("host")
+				)
+			),
+		]));

 		// Push lists to make sure they are in sync.
 		let adminlist: Set<string> = new Set();
 		let banlist: Map<string, string> = new Map();
 		let whitelist: Set<string> = new Set();

-		for (let user of this._controller.userManager.users.values()) {
+		for (let user of this._controller.users.values()) {
 			if (user.isAdmin) {
-				adminlist.add(user.name);
+				adminlist.add(user.id);
 			}
 			if (user.isBanned) {
-				banlist.set(user.name, user.banReason);
+				banlist.set(user.id, user.banReason);
 			}
 			if (user.isWhitelisted) {
-				whitelist.add(user.name);
+				whitelist.add(user.id);
 			}
 		}

@@ -279,33 +303,27 @@ export default class HostConnection extends BaseConnection {
 	}

 	async handleInstanceSaveDetailsUpdatesEvent(event: lib.InstanceSaveDetailsUpdatesEvent) {
-		const now = Date.now();
 		const updates: lib.SaveDetails[] = [];
+		const deletes: lib.SaveDetails[] = [];
 		for (const save of event.updates) {
 			const existingSave = this._controller.saves.get(save.id);
 			if (existingSave && save.equals(existingSave)) {
 				continue;
 			}
-			save.updatedAtMs = now;
-			this._controller.saves.set(save.id, save);
 			updates.push(save);
 		}
 		if (event.instanceId !== undefined) {
 			const updatedSaves = new Set(event.updates.map(s => s.id));
-			for (const [id, save] of this._controller.saves) {
-				if (save.instanceId === event.instanceId && !updatedSaves.has(id)) {
-					save.isDeleted = true;
-					save.updatedAtMs = now;
-					updates.push(save);
-					this._controller.saves.delete(id);
+			for (const save of this._controller.saves.values()) {
+				if (save.instanceId === event.instanceId && !updatedSaves.has(save.id)) {
+					deletes.push(save);
 				}
 			}
 		}
 		// Hosts eagerly send updates, which means we may get an update
-		// where nothing actualy changed.
-		if (updates.length) {
-			this._controller.savesUpdated(updates);
-		}
+		// where nothing actually changed.
+		this._controller.saves.setMany(updates);
+		this._controller.saves.deleteMany(deletes);
 	}

 	async handleLogMessageEvent(event: lib.LogMessageEvent) {
@@ -318,21 +336,18 @@ export default class HostConnection extends BaseConnection {

 	async handleInstancePlayerUpdateEvent(event: lib.InstancePlayerUpdateEvent, src: lib.Address) {
 		let instanceId = src.id;
-		let user = this._controller.userManager.users.get(event.name);
-		if (!user) {
-			user = this._controller.userManager.createUser(event.name);
-		}
+		const user = this._controller.users.getOrCreateUser(event.name);

 		if (event.type === "join") {
-			this._controller.userManager.notifyJoin(user, instanceId);
+			user.notifyJoin(instanceId);
 		} else if (event.type === "leave") {
-			this._controller.userManager.notifyLeave(user, instanceId);
+			user.notifyLeave(instanceId);
 		}

 		user.instanceStats.set(instanceId, event.stats);

 		user.recalculatePlayerStats();
-		this._controller.usersUpdated([user]);
+		user.saveRecord();

 		let instance = this._controller.instances.get(instanceId)!;
 		await lib.invokeHook(this._controller.plugins, "onPlayerEvent", instance, {
@@ -342,4 +357,55 @@ export default class HostConnection extends BaseConnection {
 			stats: event.stats,
 		});
 	}
+
+	async snoopInstanceAdminlistUpdateEvent(event: lib.InstanceAdminlistUpdateEvent, src: lib.Address) {
+		if (src.type !== lib.Address.instance) {
+			return;
+		}
+
+		const user = this._controller.users.getOrCreateUser(event.name);
+		user.set("isAdmin", event.admin);
+
+		const instance = this._controller.instances.get(src.id)!;
+		await lib.invokeHook(this._controller.plugins, "onPlayerEvent", instance, {
+			type: event.admin ? "promote" : "demote" as lib.PlayerEvent["type"],
+			name: event.name,
+			stats: user.instanceStats.get(src.id)!,
+		});
+	}
+
+	async snoopInstanceBanlistUpdateEvent(event: lib.InstanceBanlistUpdateEvent, src: lib.Address) {
+		if (src.type !== lib.Address.instance) {
+			return;
+		}
+
+		const user = this._controller.users.getOrCreateUser(event.name);
+		user.isBanned = event.banned;
+		user.banReason = event.reason;
+		user.saveRecord();
+
+		const instance = this._controller.instances.get(src.id)!;
+		await lib.invokeHook(this._controller.plugins, "onPlayerEvent", instance, {
+			type: event.banned ? "ban" : "unban" as lib.PlayerEvent["type"],
+			name: event.name,
+			stats: user.instanceStats.get(src.id)!,
+			resaon: event.reason,
+		});
+	}
+
+	async snoopInstanceWhitelistUpdateEvent(event: lib.InstanceWhitelistUpdateEvent, src: lib.Address) {
+		if (src.type !== lib.Address.instance) {
+			return;
+		}
+
+		const user = this._controller.users.getOrCreateUser(event.name);
+		user.set("isWhitelisted", event.whitelisted);
+
+		const instance = this._controller.instances.get(src.id)!;
+		await lib.invokeHook(this._controller.plugins, "onPlayerEvent", instance, {
+			type: event.whitelisted ? "whitelisted" : "unwhitelisted" as lib.PlayerEvent["type"],
+			name: event.name,
+			stats: user.instanceStats.get(src.id)!,
+		});
+	}
 }
@@ -1,10 +1,8 @@
 import { Type, Static } from "@sinclair/typebox";
 import { HostDetails } from "@clusterio/lib";

-/**
- * Info about a host known to the controller.
- */
-export default class HostInfo {
+/** Underlying data class for hosts on the controller */
+export default class HostRecord {
 	constructor(
 		/** Id of this host */
 		public id: number,
@@ -33,12 +31,12 @@ export default class HostInfo {
 		"name": Type.String(),
 		"version": Type.String(),
 		"plugins": Type.Record(Type.String(), Type.String()),
-		"connected": Type.Boolean(),
-		"remote_address": Type.String(),
-		"public_address": Type.String(),
-		"token_valid_after": Type.Number(),
-		"updated_at_ms": Type.Number(),
-		"is_deleted": Type.Boolean(),
+		"connected": Type.Optional(Type.Boolean()),
+		"remote_address": Type.Optional(Type.String()),
+		"public_address": Type.Optional(Type.String()),
+		"token_valid_after": Type.Optional(Type.Number()),
+		"updated_at_ms": Type.Optional(Type.Number()),
+		"is_deleted": Type.Optional(Type.Boolean()),
 	});

 	static fromJSON(json: Static<typeof this.jsonSchema>) {
@@ -56,19 +54,50 @@ export default class HostInfo {
 		);
 	}

-	toJSON(): Static<typeof HostInfo.jsonSchema> {
-		return {
+	toJSON() {
+		const json = {
 			id: this.id,
 			name: this.name,
 			version: this.version,
 			plugins: Object.fromEntries(this.plugins),
-			connected: this.connected,
-			remote_address: this.remoteAddress,
-			public_address: this.publicAddress,
-			token_valid_after: this.tokenValidAfter,
-			updated_at_ms: this.updatedAtMs,
-			is_deleted: this.isDeleted,
-		};
+		} as Static<typeof HostRecord.jsonSchema>;
+
+		if (this.connected !== false) {
+			json.connected = this.connected;
+		}
+		if (this.remoteAddress !== "") {
+			json.remote_address = this.remoteAddress;
+		}
+		if (this.publicAddress !== "") {
+			json.public_address = this.publicAddress;
+		}
+		if (this.tokenValidAfter !== 0) {
+			json.token_valid_after = this.tokenValidAfter;
+		}
+		if (this.updatedAtMs !== 0) {
+			json.updated_at_ms = this.updatedAtMs;
+		}
+		if (this.isDeleted !== false) {
+			json.is_deleted = this.isDeleted;
+		}
+
+		return json;
+	}
+
+
+	static fromHostDetails(details: HostDetails, plugins: Map<string, string>) {
+		return new HostRecord(
+			details.id,
+			details.name,
+			details.version,
+			plugins,
+			details.connected,
+			details.remoteAddress,
+			details.publicAddress,
+			details.tokenValidAfter,
+			details.updatedAtMs,
+			details.isDeleted,
+		);
 	}

 	toHostDetails() {
@@ -85,4 +114,3 @@ export default class HostInfo {
 		);
 	}
 }
-
@@ -1,55 +0,0 @@
-import * as lib from "@clusterio/lib";
-import { Static, Type } from "@sinclair/typebox";
-
-
-/**
- * Runtime status of an instance on the controller
- * @alias module:controller/src/InstanceInfo
- */
-export default class InstanceInfo {
-	constructor(
-		public config: lib.InstanceConfig,
-		public status: lib.InstanceStatus,
-		public gamePort?: number,
-		public updatedAtMs = 0,
-	) {
-		this.config = config;
-		this.status = status;
-	}
-
-	static jsonSchema = Type.Object({
-		"config": lib.InstanceConfig.jsonSchema,
-		"status": lib.InstanceStatus,
-		"gamePort": Type.Optional(Type.Number()),
-		"updatedAtMs": Type.Optional(Type.Number()),
-	});
-
-	static fromJSON(json: Static<typeof this.jsonSchema>, location: lib.ConfigLocation) {
-		return new this(
-			lib.InstanceConfig.fromJSON(json.config, location),
-			json.status,
-			json.gamePort,
-			json.updatedAtMs,
-		);
-	}
-
-	toInstanceDetails() {
-		return new lib.InstanceDetails(
-			this.config.get("instance.name"),
-			this.id,
-			this.config.get("instance.assigned_host") ?? undefined,
-			this.gamePort,
-			this.status,
-			this.updatedAtMs,
-		);
-	}
-
-	get isDeleted() {
-		return this.status === "deleted";
-	}
-
-	/** Shorthand for `instance.config.get("instance.id")` */
-	get id():number {
-		return this.config.get("instance.id");
-	}
-}
@@ -0,0 +1,274 @@
+import * as lib from "@clusterio/lib";
+
+import type Controller from "./Controller";
+import type HostConnection from "./HostConnection";
+import InstanceRecord from "./InstanceRecord";
+
+export default class InstanceManager {
+	private static readonly DefaultFactorioSettings = {
+		tags: ["clusterio"],
+		max_players: 0,
+		visibility: { public: true, lan: true },
+		game_password: "",
+		require_user_verification: true,
+		max_upload_in_kilobytes_per_second: 0,
+		max_upload_slots: 5,
+		ignore_player_limit_for_returning_players: false,
+		allow_commands: "admins-only",
+		autosave_interval: 10,
+		autosave_slots: 5,
+		afk_autokick_interval: 0,
+		auto_pause: false,
+		only_admins_can_pause_the_game: true,
+		autosave_only_on_server: true,
+		non_blocking_saving: false,
+	} as const;
+
+	constructor(
+		public readonly records: lib.SubscribableDatastore<InstanceRecord>,
+		private readonly _controller: Controller,
+	) {
+		for (const instance of records.values()) {
+			this.addInstanceHooks(instance);
+		}
+	}
+
+	/* ------------------------------------------------------------------------- */
+	/* Basic Accessors                                                           */
+	/* ------------------------------------------------------------------------- */
+
+	has(id: InstanceRecord["id"]): boolean {
+		return this.records.has(id);
+	}
+
+	getMutable(id: InstanceRecord["id"]): InstanceRecord | undefined {
+		return this.records.get(id);
+	}
+
+	get(id: InstanceRecord["id"]): Readonly<InstanceRecord> | undefined {
+		return this.getMutable(id);
+	}
+
+	valuesMutable(): IterableIterator<InstanceRecord> {
+		return this.records.values();
+	}
+
+	values(): IterableIterator<Readonly<InstanceRecord>> {
+		return this.valuesMutable();
+	}
+
+	/**
+	 * Get instance by ID for a request.
+	 *
+	 * Convenience wrapper around {@link getMutable} that throws
+	 * if the instance does not exist.
+	 *
+	 * @param instanceId - ID of instance to get.
+	 * @returns The instance record.
+	 * @throws {module:lib.RequestError} if the instance does not exist.
+	 */
+	getForRequest(instanceId: number): InstanceRecord {
+		const instance = this.records.get(instanceId);
+		if (!instance) {
+			throw new lib.RequestError(`Instance with ID ${instanceId} does not exist`);
+		}
+		return instance;
+	}
+
+	/* ------------------------------------------------------------------------- */
+	/* Internal Helpers                                                          */
+	/* ------------------------------------------------------------------------- */
+
+	private async _notifyStatusChanged(
+		instance: InstanceRecord,
+		prev?: lib.InstanceStatus,
+	): Promise<void> {
+		await lib.invokeHook(
+			this._controller.plugins,
+			"onInstanceStatusChanged",
+			instance,
+			prev,
+		);
+	}
+
+	private async _notifyConfigFieldChanged(
+		instance: InstanceRecord,
+		field: string,
+		curr: unknown,
+		prev: unknown,
+	): Promise<void> {
+		await lib.invokeHook(
+			this._controller.plugins,
+			"onInstanceConfigFieldChanged",
+			instance,
+			field,
+			curr,
+			prev,
+		);
+	}
+
+	/**
+	 * Attach change listeners to an instance record.
+	 *
+	 * Hooks into configuration field changes and ensures the datastore
+	 * is updated and plugins are notified when a config field changes.
+	 *
+	 * @param instance - The instance record to attach hooks to.
+	 * @internal
+	 */
+	addInstanceHooks(instance: InstanceRecord): void {
+		instance.config.on("fieldChanged", (field: string, curr: unknown, prev: unknown) => {
+			this.records.set(instance);
+			this._notifyConfigFieldChanged(instance, field, curr, prev);
+		});
+	}
+
+	/* ------------------------------------------------------------------------- */
+	/* Lifecycle                                                                 */
+	/* ------------------------------------------------------------------------- */
+
+	/**
+	 * Create a new instance.
+	 *
+	 * @example
+	 * const config = new lib.InstanceConfig("controller", { "instance.name": "My instance" });
+	 * const instance = await controller.instances.createInstance(config);
+	 *
+	 * @param instanceConfig - Config to base the newly created instance on.
+	 * @param _suppressChanges - When true, side effects are suppressed, caller takes ownership.
+	 * @returns The created instance record.
+	 * @throws {module:lib.RequestError} if an instance with the same ID already exists.
+	 */
+	async createInstance(
+		instanceConfig: lib.InstanceConfig,
+		_suppressChanges?: boolean,
+	): Promise<InstanceRecord> {
+		const instanceId = instanceConfig.get("instance.id");
+		if (this.records.has(instanceId)) {
+			throw new lib.RequestError(`Instance with ID ${instanceId} already exists`);
+		}
+
+		const controllerName = this._controller.config.get("controller.name");
+		instanceConfig.set("factorio.settings", {
+			name: `${controllerName} - ${instanceConfig.get("instance.name")}`,
+			description: `Clusterio instance for ${controllerName}`,
+			...InstanceManager.DefaultFactorioSettings,
+			...instanceConfig.get("factorio.settings"),
+		});
+
+		const instance = new InstanceRecord(instanceConfig, "unassigned");
+		this.addInstanceHooks(instance);
+
+		if (!_suppressChanges) {
+			this.records.set(instance);
+			await this._notifyStatusChanged(instance);
+		}
+
+		return instance;
+	}
+
+	/**
+	 * Change the assigned host of an instance.
+	 *
+	 * Unassigns the instance from the currently assigned host (if connected)
+	 * and assigns it to the provided host.
+	 *
+	 * This is the only supported way of modifying the
+	 * `instance.assigned_host` configuration entry.
+	 *
+	 * Note:
+	 * - This does NOT transfer any files or saves between hosts.
+	 * - If the instance is already assigned to the specified host, no action is taken.
+	 *
+	 * @param instanceId - ID of instance to assign.
+	 * @param hostId - ID of host to assign the instance to. If undefined,
+	 * the instance will be unassigned.
+	 *
+	 * @throws {module:lib.RequestError} if the instance does not exist.
+	 * @throws {module:lib.RequestError} if the target host is not connected.
+	 */
+	async assignInstance(
+		instanceId: number,
+		hostId: number | null,
+	): Promise<void> {
+		const instance = this.getForRequest(instanceId);
+		const hostConnections = this._controller.wsServer.hostConnections;
+
+		const currentAssignedHost = instance.config.get("instance.assigned_host");
+		if (currentAssignedHost === hostId) {
+			return;
+		}
+
+		let newHostConnection: HostConnection | undefined;
+		if (hostId !== null) {
+			newHostConnection = hostConnections.get(hostId);
+			if (!newHostConnection) {
+				throw new lib.RequestError("Target host is not connected to the controller");
+			}
+		}
+
+		if (currentAssignedHost !== null) {
+			const oldHostConnection = hostConnections.get(currentAssignedHost);
+			if (oldHostConnection && !oldHostConnection.connector.closing) {
+				await oldHostConnection.send(
+					new lib.InstanceUnassignInternalRequest(instanceId),
+				);
+			}
+		}
+
+		this._controller.clearSavesOfInstance(instanceId);
+		instance.config.set("instance.assigned_host", hostId);
+
+		if (newHostConnection) {
+			await newHostConnection.send(
+				new lib.InstanceAssignInternalRequest(instanceId, instance.config.toRemote("host")),
+			);
+		} else {
+			instance.status = "unassigned";
+		}
+
+		this.records.set(instance);
+	}
+
+	/**
+	 * Unassign an instance from its current host.
+	 *
+	 * Convenience wrapper around {@link assignInstance} that removes
+	 * the assigned host.
+	 *
+	 * @param instanceId - ID of instance to unassign.
+	 */
+	async unassignInstance(instanceId: number): Promise<void> {
+		return this.assignInstance(instanceId, null);
+	}
+
+	/**
+	 * Delete an instance permanently.
+	 *
+	 * Sends a delete request to the assigned host (if any),
+	 * removes the instance from the datastore,
+	 * clears associated saves and user statistics.
+	 *
+	 * @param instanceId - ID of instance to delete.
+	 *
+	 * @throws {module:lib.RequestError} if the instance does not exist.
+	 */
+	async deleteInstance(instanceId: number): Promise<void> {
+		const instance = this.getForRequest(instanceId);
+		const hostId = instance.config.get("instance.assigned_host");
+
+		if (hostId !== null) {
+			await this._controller.sendTo(
+				{ hostId },
+				new lib.InstanceDeleteInternalRequest(instanceId),
+			);
+		}
+
+		const prevStatus = instance.status;
+		this.records.delete(instance);
+		this._controller.clearSavesOfInstance(instanceId);
+		this._controller.users.clearStatsOfInstance(instanceId);
+
+		await this._notifyStatusChanged(instance, prevStatus);
+	}
+}
@@ -0,0 +1,99 @@
+import * as lib from "@clusterio/lib";
+import { Static, Type } from "@sinclair/typebox";
+
+/** Underlying data class for instances on the controller */
+export default class InstanceRecord {
+	constructor(
+		public config: lib.InstanceConfig,
+		public status: lib.InstanceStatus,
+		public gamePort?: number,
+		public factorioVersion?: lib.TargetVersion,
+		public startedAtMs = 0,
+		public updatedAtMs = 0,
+	) {
+		this.config = config;
+		this.status = status;
+	}
+
+	get id(): number {
+		return this.config.get("instance.id");
+	}
+
+	get isDeleted() {
+		return this.status === "deleted";
+	}
+
+	set isDeleted(value: boolean) {
+		if (value === false) {
+			throw new Error("Setting isDeleted to false is not supported, use status instead.");
+		}
+		this.status = "deleted";
+	}
+
+	static jsonSchema = Type.Object({
+		"config": lib.InstanceConfig.jsonSchema,
+		"status": lib.InstanceStatus,
+		"gamePort": Type.Optional(Type.Number()),
+		"startedAtMs": Type.Optional(Type.Number()),
+		"updatedAtMs": Type.Optional(Type.Number()),
+		"factorioVersion": Type.Optional(lib.TargetVersionSchema),
+	});
+
+	static fromJSON(json: Static<typeof this.jsonSchema>) {
+		return new this(
+			lib.InstanceConfig.fromJSON(json.config, "controller"),
+			json.status,
+			json.gamePort,
+			json.factorioVersion,
+			json.startedAtMs,
+			json.updatedAtMs,
+		);
+	}
+
+	toJSON(): Static<typeof InstanceRecord.jsonSchema> {
+		const json: any = {
+			config: this.config.toJSON(),
+			status: this.status,
+		};
+
+		if (this.gamePort !== undefined) {
+			json.gamePort = this.gamePort;
+		}
+		if (this.factorioVersion !== undefined) {
+			json.factorioVersion = this.factorioVersion;
+		}
+		if (this.startedAtMs !== 0) {
+			json.startedAtMs = this.startedAtMs;
+		}
+		if (this.updatedAtMs !== 0) {
+			json.updatedAtMs = this.updatedAtMs;
+		}
+
+		return json;
+	}
+
+	toInstanceDetails() {
+		return new lib.InstanceDetails(
+			this.config.get("instance.name"),
+			this.id,
+			this.config.get("instance.assigned_host") ?? undefined,
+			this.gamePort,
+			this.status,
+			this.factorioVersion,
+			this.startedAtMs,
+			this.updatedAtMs,
+			this.config.get("instance.exclude_from_start_all"),
+		);
+	}
+
+	static fromInstanceDetails(details: lib.InstanceDetails, config: lib.InstanceConfig) {
+		return new InstanceRecord(
+			config,
+			details.status,
+			details.gamePort,
+			details.factorioVersion,
+			details.startedAtMs,
+			details.updatedAtMs,
+		);
+	}
+}
@@ -0,0 +1,146 @@
+
+import {
+	IUser, Role, SubscribableDatastore,
+	PermissionError, permissions,
+} from "@clusterio/lib";
+
+import UserRecord from "./UserRecord";
+import { Static } from "@sinclair/typebox";
+
+/**
+ * Represents a user as viewed from the controller.
+ *
+ * All methods are safe to use when readonly.
+ * Only use mutable when needing to change multiple values.
+ */
+export default class User extends UserRecord implements IUser {
+	constructor(
+		private _controllerUsers: SubscribableDatastore<UserRecord>,
+		private _controllerRoles: SubscribableDatastore<Role>,
+		...args: ConstructorParameters<typeof UserRecord>
+	) {
+		super(...args);
+	}
+
+	static fromJSON(
+		json: Static<typeof this.jsonSchema>,
+		_controllerUsers: SubscribableDatastore<UserRecord>,
+		_controllerRoles: SubscribableDatastore<Role>,
+	) {
+		return this.fromUserRecord(
+			UserRecord.fromJSON(json),
+			_controllerUsers,
+			_controllerRoles,
+		);
+	}
+
+	static fromUserRecord(
+		userRecord: UserRecord,
+		_controllerUsers: SubscribableDatastore<UserRecord>,
+		_controllerRoles: SubscribableDatastore<Role>,
+	): User {
+		return new this(
+			_controllerUsers,
+			_controllerRoles,
+			userRecord.tokenValidAfter,
+			userRecord.name,
+			userRecord.roleIds,
+			userRecord.instances,
+			userRecord.isAdmin,
+			userRecord.isBanned,
+			userRecord.isWhitelisted,
+			userRecord.banReason,
+			userRecord.updatedAtMs,
+			userRecord.isDeleted,
+			userRecord.instanceStats,
+		);
+	}
+
+	/** Roles this user has */
+	get roles(): ReadonlySet<Readonly<Role>> {
+		return new Set([...this.roleIds].map(
+			id => this._controllerRoles.get(id)
+		).filter(
+			(r): r is Role => Boolean(r)
+		));
+	}
+
+	/** Save the underlying user record */
+	saveRecord() {
+		this._controllerUsers.set(this);
+	}
+
+	/** Set a property on the underlying record, then save it. */
+	set<K extends keyof this>(key: K, value: this[K]) {
+		this[key] = value;
+		this.saveRecord();
+	}
+
+	/**
+	 * Invalidate current tokens for the user
+	 *
+	 * Sets the tokenValidAfter property to the current time, which causes
+	 * all currently issued tokens for the user to become invalid.
+	 */
+	invalidateToken() {
+		this.tokenValidAfter = Math.floor(Date.now() / 1000);
+		this.saveRecord();
+	}
+
+	/** Add a role to this user */
+	addRole(roleId: number) {
+		const role = this._controllerRoles.get(roleId);
+		if (!role) {
+			throw new Error(`role ${roleId} does not exist`);
+		}
+		this.roleIds.add(roleId);
+		this.saveRecord();
+	}
+
+	/** Remove a role from user */
+	removeRole(roleId: number) {
+		if (!this.roleIds.delete(roleId)) {
+			return false;
+		}
+		this.saveRecord();
+		return true;
+	}
+
+	/** Set a user as being online on a specific instance */
+	notifyJoin(instanceId: number) {
+		this.instances.add(instanceId);
+		this.saveRecord();
+	}
+
+	/** Set a user as being offline on a specific instance */
+	notifyLeave(instanceId: number) {
+		this.instances.delete(instanceId);
+		this.saveRecord();
+	}
+
+	/** Clear the stats of a player on a specific instance */
+	clearInstanceStats(instanceId: number) {
+		this.instances.delete(instanceId);
+		this.instanceStats.delete(instanceId);
+		this.recalculatePlayerStats();
+		this.saveRecord();
+	}
+
+	checkPermission(permission: string) {
+		if (!permissions.has(permission)) {
+			throw new Error(`permission ${permission} does not exist`);
+		}
+
+		for (const roleId of this.roleIds) {
+			const role = this._controllerRoles.get(roleId);
+			if (!role) {
+				continue;
+			}
+			if (role.permissions.has("core.admin") || role.permissions.has(permission)) {
+				return;
+			}
+		}
+
+		throw new PermissionError("Permission denied");
+	}
+}
@@ -3,123 +3,162 @@ import jwt from "jsonwebtoken";

 import * as lib from "@clusterio/lib";

-import ControllerUser from "./ControllerUser";
+import User from "./User";
+import UserRecord from "./UserRecord";

 /**
- * Manages users and roles
+ * Access layer for users on the controller.
+ *
+ * In performance critical paths the raw records can be accessed directly.
+ * Otherwise this class will wrap data in a view class with a set and save method.
+ *
 * @alias module:controller/src/UserManager
 */
 export default class UserManager {
-	roles: Map<number, lib.Role> = new Map();
-	users: Map<string, ControllerUser> = new Map();
-	dirty = false;
-
-	/**
-	 * Set of users currently online in the cluster.
-	 */
-	onlineUsers = new Set<ControllerUser>();
-
 	constructor(
-		private _config: lib.ControllerConfig
+		public records: lib.SubscribableDatastore<UserRecord>,
+		private _controllerRoles: lib.SubscribableDatastore<lib.Role>,
+		private _controllerConfig: lib.ControllerConfig,
 	) {
 	}

-	async load(filePath: string): Promise<void> {
+	/**
+	 * Prior to 2.0.0-alpha.22 users and roles were stored in a single file.
+	 * This migration separates them so they can be loaded by datastore.
+	 *
+	 * @param usersFilePath The src and dst file path for the users json file
+	 * @param rolesFilePath The dst for the roles json file
+	 */
+	static async attemptMigrateLegacyUsersFile(usersFilePath: string, rolesFilePath: string) {
 		try {
-			let content = JSON.parse(await fs.readFile(filePath, { encoding: "utf8" }));
-			for (let serializedRole of content.roles) {
-				let role = lib.Role.fromJSON(serializedRole);
-				this.roles.set(role.id, role);
+			const combinedJson = JSON.parse(await fs.readFile(usersFilePath, { encoding: "utf8" }));
+			if (!("roles" in combinedJson)) {
+				return; // Files are already split, no action required
 			}
-
-			for (let serializedUser of content.users) {
-				let user = ControllerUser.fromJSON(serializedUser, this);
-				this.users.set(user.name, user);
+			if (!("users" in combinedJson)) {
+				throw new Error("Legacy users json does not contain users property");
 			}

+			// We intentionally write the roles first because if it fails then the old user file will still contain them
+			await lib.safeOutputFile(rolesFilePath, JSON.stringify(combinedJson.roles));
+			await lib.safeOutputFile(usersFilePath, JSON.stringify(combinedJson.users));
 		} catch (err: any) {
 			if (err.code !== "ENOENT") {
 				throw err;
 			}
-
-			// Create default roles if loading failed
-			lib.ensureDefaultAdminRole(this.roles);
-			lib.ensureDefaultPlayerRole(this.roles);
 		}
 	}

-	async save(filePath:string): Promise<void> {
-		let serializedRoles = [];
-		for (let role of this.roles.values()) {
-			serializedRoles.push(role.toJSON());
-		}
+	/* ------------------------------------------------------------------------- */
+	/* Basic Accessors                                                           */
+	/* ------------------------------------------------------------------------- */

-		let serializedUsers = [];
-		for (let user of this.users.values()) {
-			serializedUsers.push(user.toJSON(true));
-		}
-
-		let serialized = {
-			users: serializedUsers,
-			roles: serializedRoles,
-		};
-		this.dirty = false;
-		await lib.safeOutputFile(filePath, JSON.stringify(serialized, null, "\t"));
+	has(id: UserRecord["id"]) {
+		return this.records.has(id);
 	}

+	getMutable(id: UserRecord["id"]) {
+		const userRecord = this.records.getMutable(id);
+		if (!userRecord) {
+			return undefined;
+		}
+
+		return User.fromUserRecord(
+			userRecord,
+			this.records,
+			this._controllerRoles,
+		);
+	}
+
+	get(id: UserRecord["id"]): Readonly<User> | undefined {
+		return this.getMutable(id);
+	}
+
+	hasName(name: UserRecord["name"]) {
+		return this.has(name.toLowerCase());
+	}
+
+	getByNameMutable(name: UserRecord["name"]) {
+		return this.getMutable(name.toLowerCase());
+	}
+
+	getByName(name: UserRecord["name"]) {
+		return this.get(name.toLowerCase());
+	}
+
+	* valuesMutable(): IterableIterator<User> {
+		const roles = this._controllerRoles;
+		const users = this.records;
+
+		for (const record of users.values()) {
+			yield User.fromUserRecord(record, users, roles);
+		}
+	}
+
+	values(): IterableIterator<Readonly<User>> {
+		return this.valuesMutable();
+	}
+
+	/* ------------------------------------------------------------------------- */
+	/* Lifecycle                                                                 */
+	/* ------------------------------------------------------------------------- */
+
 	/**
 	 * Creates a new user and add it to the user database.
 	 * @param name - Name of the user to create.
 	 * @returns The created user.
 	 */
-	createUser(name:string): ControllerUser {
-		if (this.users.has(name)) {
+	createUser(name: string): User {
+		if (this.getByName(name)) {
 			throw new Error(`User '${name}' already exists`);
 		}

 		let roles = new Set<number>();
-		let defaultRoleId = this._config.get("controller.default_role_id");
-		if (defaultRoleId !== null && this.roles.has(defaultRoleId)) {
+		let defaultRoleId = this._controllerConfig.get("controller.default_role_id");
+		if (defaultRoleId !== null && this._controllerRoles.has(defaultRoleId)) {
 			roles.add(defaultRoleId);
 		}

-		let user = new ControllerUser(this, 0, name, roles);
-		this.users.set(name, user);
-		this.dirty = true;
+		const user = new User(this.records, this._controllerRoles, 0, name, roles);
+		this.records.set(user);
 		return user;
 	}

+	/** Get or create a user with a given name. */
+	getOrCreateUser(name: string): User {
+		return this.getByNameMutable(name) ?? this.createUser(name);
+	}
+
 	/**
-	 * Sign access token for the given user name
+	 * Deletes an existing user
 	 *
-	 * @param name - user name to sign token for
+	 * @param user - user to delete
+	 */
+	deleteUser(user: UserRecord) {
+		return this.records.delete(user);
+	}
+
+	/* ------------------------------------------------------------------------- */
+	/* Helpers                                                                   */
+	/* ------------------------------------------------------------------------- */
+
+	/**
+	 * Sign access token for the given user
+	 *
+	 * @param user - user to sign token for
 	 * @returns JWT access token for the user.
 	 */
-	signUserToken(name: string): string {
+	signUserToken(user: UserRecord): string {
 		return jwt.sign(
-			{ aud: "user", user: name },
-			Buffer.from(this._config.get("controller.auth_secret"), "base64")
+			{ aud: "user", user: user.id },
+			Buffer.from(this._controllerConfig.get("controller.auth_secret"), "base64")
 		);
 	}

-	notifyJoin(user: ControllerUser, instance_id: number) {
-		user.instances.add(instance_id);
-		this.onlineUsers.add(user);
-	}
-
-	notifyLeave(user: ControllerUser, instance_id: number) {
-		user.instances.delete(instance_id);
-		if (!user.instances.size) {
-			this.onlineUsers.delete(user);
-		}
-	}
-
+	/** Clear all player stats for specific instance */
 	clearStatsOfInstance(instanceId: number) {
-		for (const user of this.users.values()) {
-			this.notifyLeave(user, instanceId);
-			user.instanceStats.delete(instanceId);
-			user.recalculatePlayerStats();
+		for (const user of this.values()) {
+			user.clearInstanceStats(instanceId);
 		}
-		this.dirty = true;
 	}
 }
@@ -0,0 +1,102 @@
+import { UserDetails } from "@clusterio/lib";
+import { Type, Static } from "@sinclair/typebox";
+
+/** Underlying data class for users on the controller */
+export default class UserRecord extends UserDetails {
+	constructor(
+		/** Unix time in seconds the user token must be issued after to be valid.  */
+		public tokenValidAfter = 0,
+		...args: ConstructorParameters<typeof UserDetails>
+	) {
+		super(...args);
+	}
+
+	static jsonSchema = Type.Object({
+		token_valid_after: Type.Optional(Type.Number()),
+		...UserDetails.jsonSchema.properties,
+	});
+
+	// _a and _b are a ts workaround for allowing User to have extra arguments
+	static fromJSON(json: Static<typeof this.jsonSchema>, _a?: any, _b?: any) {
+		return this.fromUserDetails(
+			UserDetails.fromJSON(json),
+			json.token_valid_after,
+		);
+	}
+
+	toJSON() {
+		const json = super.toJSON() as Static<typeof UserRecord.jsonSchema>;
+
+		if (this.tokenValidAfter > 0) {
+			json.token_valid_after = this.tokenValidAfter;
+		}
+
+		return json;
+	}
+
+	static fromUserDetails(
+		userDetails: UserDetails,
+		tokenValidAfter = 0,
+	) {
+		return new this(
+			tokenValidAfter,
+			userDetails.name,
+			userDetails.roleIds,
+			userDetails.instances,
+			userDetails.isAdmin,
+			userDetails.isBanned,
+			userDetails.isWhitelisted,
+			userDetails.banReason,
+			userDetails.updatedAtMs,
+			userDetails.isDeleted,
+			userDetails.instanceStats,
+		);
+	}
+
+	toUserDetails() {
+		return new UserDetails(
+			this.name,
+			this.roleIds,
+			this.instances,
+			this.isAdmin,
+			this.isBanned,
+			this.isWhitelisted,
+			this.banReason,
+			this.updatedAtMs,
+			this.isDeleted,
+			this.instanceStats,
+		);
+	}
+
+	/**
+	 * Merge another user into this one, must have matching ids, user is not deleted
+	 * @param otherUser - User who's details are merged from
+	*/
+	merge(otherUser: UserDetails) {
+		if (this.id !== otherUser.id) {
+			throw new Error("Cannot merge users with different ids");
+		}
+
+		// Merge properties
+		this.roleIds = new Set([...this.roleIds, ...otherUser.roleIds]);
+		this.instances = new Set([...this.instances, ...otherUser.instances]);
+		this.isAdmin = this.isAdmin && otherUser.isAdmin; // More secure to use && rather ||
+		this.isBanned = this.isBanned || otherUser.isBanned;
+		this.isWhitelisted = this.isWhitelisted || otherUser.isWhitelisted;
+		this.banReason = this.updatedAtMs > otherUser.updatedAtMs ? this.banReason : otherUser.banReason;
+		this.updatedAtMs = Date.now();
+
+		// Merge instance stats
+		const thisInstanceStats = this.instanceStats;
+		for (const [instanceId, instanceStats] of otherUser.instanceStats.entries()) {
+			if (thisInstanceStats.has(instanceId)) {
+				thisInstanceStats.get(instanceId)!.merge(instanceStats);
+			} else {
+				thisInstanceStats.set(instanceId, instanceStats);
+			}
+		}
+
+		// Player stats must be recalculated after modifying instance stats
+		this.recalculatePlayerStats();
+	}
+}
@@ -78,11 +78,11 @@ export default class WsServer {

 		let disconnectTasks = [];
 		for (let controlConnection of this.controlConnections.values()) {
-			disconnectTasks.push(controlConnection.disconnect(1001, "Server Quit"));
+			disconnectTasks.push(controlConnection.disconnect(lib.ConnectionClosed.GoingAway, "Server Quit"));
 		}

 		for (let hostConnection of this.hostConnections.values()) {
-			disconnectTasks.push(hostConnection.disconnect(1001, "Server Quit"));
+			disconnectTasks.push(hostConnection.disconnect(lib.ConnectionClosed.GoingAway, "Server Quit"));
 		}

 		logger.info(`WsServer | Waiting for ${disconnectTasks.length} connectors to close`);
@@ -97,7 +97,7 @@ export default class WsServer {
 		}

 		for (let socket of this.pendingSockets) {
-			socket.close(1001, "Server Quit");
+			socket.close(lib.ConnectionClosed.GoingAway, "Server Quit");
 		}
 	}

@@ -170,7 +170,7 @@ export default class WsServer {
 ${err.stack}`
 				);
 				wsRejectedConnectionsCounter.inc();
-				socket.close(1011, "Unexpected error");
+				socket.close(lib.ConnectionClosed.InternalError, "Unexpected error");
 			});
 		});
 	}
@@ -184,7 +184,7 @@ ${err.stack}`
 		} catch (err: any) {
 			logger.verbose(`WsServer | closing ${this.remoteAddr(req)} after receiving invalid message`);
 			wsRejectedConnectionsCounter.inc();
-			socket.close(1002, `Invalid message: ${err.message}`);
+			socket.close(lib.ConnectionClosed.ProtocolError, `Invalid message: ${err.message}`);
 			return;
 		}

@@ -196,14 +196,14 @@ ${err.stack}`
 		if (message.type !== "registerHost" && message.type !== "registerControl") {
 			logger.verbose(`WsServer | closing ${this.remoteAddr(req)} after receiving invalid handshake`);
 			wsRejectedConnectionsCounter.inc();
-			socket.close(1002, "Bad handshake");
+			socket.close(lib.ConnectionClosed.ProtocolError, "Bad handshake");
 			return;
 		}

 		if (this.stopAcceptingNewSessions) {
 			logger.verbose(`WsServer | closing ${this.remoteAddr(req)}, server is shutting down`);
 			wsRejectedConnectionsCounter.inc();
-			socket.close(1001, "Shutting down");
+			socket.close(lib.ConnectionClosed.GoingAway, "Shutting down");
 			return;
 		}

@@ -239,6 +239,13 @@ ${err.stack}`
 	}

 	async registerHost(data: lib.RegisterHostData, socket: WebSocket, req: IncomingMessage) {
+		if (this.controller.recoveryMode) {
+			logger.warn(`Recovery | rejected host connection attempt for ${this.remoteAddr(req)}`);
+			wsRejectedConnectionsCounter.inc();
+			socket.close(lib.ConnectionClosed.RecoveryMode, "Connection Refused: Controller in recovery mode");
+			return;
+		}
+
 		try {
 			let tokenPayload = jwt.verify(
 				data.token,
@@ -263,15 +270,26 @@ ${err.stack}`
 		} catch (err: any) {
 			logger.verbose(`WsServer | authentication failed for ${this.remoteAddr(req)}`);
 			wsRejectedConnectionsCounter.inc();
-			socket.close(4003, `Authentication failed: ${err.message}`);
+			socket.close(lib.ConnectionClosed.Unauthorized, `Authentication failed: ${err.message}`);
 			return;
 		}

-		let [connector, sessionToken] = this.createSession(new lib.Address(lib.Address.host, data.id));
 		let connection = this.hostConnections.get(data.id);
 		if (connection) {
-			logger.verbose(`WsServer | disconnecting existing connection for host ${data.id}`);
-			await connection.disconnect(1008, "Registered from another connection");
+			if (connection.remoteAddress !== this.remoteAddr(req)) {
+				logger.verbose(
+					`WsServer | disallowed duplicate connection from ${this.remoteAddr(req)} for host ${data.id}`
+				);
+				wsRejectedConnectionsCounter.inc();
+				socket.close(lib.ConnectionClosed.PolicyViolation, "Host already connected from another address");
+				return;
+			}
+			logger.verbose(
+				`WsServer | disconnecting duplicate connection from host ${data.id}`
+			);
+			await connection.disconnect(
+				lib.ConnectionClosed.PolicyViolation, "Newer connection for host from same address"
+			);
 		}

 		logger.info(
@@ -284,7 +302,11 @@ ${err.stack}`
 			);
 		}

-		connection = new HostConnection(data, connector, this.controller, this.remoteAddr(req));
+		let [connector, sessionToken] = this.createSession(new lib.Address(lib.Address.host, data.id));
+
+		// Handle close before HostConnection does. This avoids a host
+		// connection event happening between the connection breaking and
+		// it being removed from the host connections list.
 		connector.on("close", () => {
 			if (this.hostConnections.get(data.id) === connection) {
 				this.hostConnections.delete(data.id);
@@ -292,6 +314,8 @@ ${err.stack}`
 				logger.warn("Unlisted HostConnection closed");
 			}
 		});
+
+		connection = new HostConnection(data, connector, this.controller, this.remoteAddr(req));
 		this.hostConnections.set(data.id, connection);
 		let src = new lib.Address(lib.Address.host, data.id);
 		connector.ready(socket, src, sessionToken, undefined);
@@ -310,7 +334,7 @@ ${err.stack}`
 				throw new Error("unexpected JsonWebToken type");
 			}

-			user = this.controller.userManager.users.get(tokenPayload.user);
+			user = this.controller.users.getByNameMutable(tokenPayload.user);
 			if (!user) {
 				throw new Error("invalid user");
 			}
@@ -322,7 +346,7 @@ ${err.stack}`
 		} catch (err: any) {
 			logger.verbose(`WsServer | authentication failed for ${this.remoteAddr(req)}`);
 			wsRejectedConnectionsCounter.inc();
-			socket.close(4003, `Authentication failed: ${err.message}`);
+			socket.close(lib.ConnectionClosed.Unauthorized, `Authentication failed: ${err.message}`);
 			return;
 		}

@@ -331,10 +355,10 @@ ${err.stack}`
 		let [connector, sessionToken] = this.createSession(new lib.Address(lib.Address.control, id));

 		logger.verbose(`WsServer | registered control ${id} from ${this.remoteAddr(req)}`);
-		let connection = new ControlConnection(data, connector, this.controller, user, id);
 		connector.on("close", () => {
 			this.controlConnections.delete(id);
 		});
+		let connection = new ControlConnection(data, connector, this.controller, user, id);
 		this.controlConnections.set(id, connection);
 		let account = new lib.AccountDetails(
 			user.name,
@@ -1,6 +1,7 @@
 import type WebSocket from "ws";

 import events from "events";
+import assert from "assert/strict";

 import * as lib from "@clusterio/lib";
 const { logger } = lib;
@@ -113,8 +114,7 @@ export default class WsServerConnector extends lib.WebSocketBaseConnector {

 	_timedOut() {
 		logger.verbose("Connector | Connection timed out");
-		this._reset();
-		this.emit("close");
+		this._close();
 	}

 	_attachSocketHandlers() {
@@ -130,8 +130,7 @@ export default class WsServerConnector extends lib.WebSocketBaseConnector {
 			this._socket = null;

 			if (this._closing) {
-				this._reset();
-				this.emit("close");
+				this._close();

 			} else {
 				this._state = "resuming";
@@ -187,8 +186,7 @@ export default class WsServerConnector extends lib.WebSocketBaseConnector {
 		}

 		if (this._state === "resuming") {
-			this._reset();
-			this.emit("close");
+			this._close();
 			return;
 		}

@@ -223,8 +221,7 @@ export default class WsServerConnector extends lib.WebSocketBaseConnector {
 	 */
 	setClosing() {
 		if (this._state === "resuming") {
-			this._reset();
-			this.emit("close");
+			this._close();
 			return;
 		}

@@ -109,9 +109,7 @@ function getPlugins(req: Request, res: Response) {
 	for (let pluginInfo of req.app.locals.controller.pluginInfos) {
 		let name = pluginInfo.name;
 		let loaded = req.app.locals.controller.plugins.has(name);
-		let enabled = loaded && req.app.locals.controller.config.get(
-			`${pluginInfo.name}.load_plugin` as keyof lib.ControllerConfigFields,
-		) as unknown as boolean;
+		let enabled = loaded && req.app.locals.controller.config.get(`${pluginInfo.name}.load_plugin`);
 		// Note: Cast through unknown is needed because load_plugin is
 		// defined at runtime and no other fields in the controller config
 		// currently have the boolean type.
@@ -136,6 +134,12 @@ function getPlugins(req: Request, res: Response) {
 	res.send(plugins);
 }

+function getClusterName(req: Request, res: Response) {
+	const controller: Controller = req.app.locals.controller;
+	const clusterName = controller.config.get("controller.name");
+	res.json({ name: clusterName });
+}
+
 function validateHostToken(req: Request, res: Response, next: any) {
 	let token = req.header("x-access-token");
 	if (!token) {
@@ -185,7 +189,7 @@ function validateUserToken(req: Request, res: Response, next: any) {
 		if (typeof tokenPayload === "string") {
 			throw new Error("unexpected JsonWebToken type");
 		}
-		let user = req.app.locals.controller.userManager.users.get(tokenPayload.user);
+		let user = req.app.locals.controller.users.getByName(tokenPayload.user);
 		if (!user) {
 			throw new Error("invalid user");
 		}
@@ -218,7 +222,7 @@ async function uploadExport(req: Request, res: Response) {
 		res.sendStatus(400);
 		return;
 	}
-	let modPack = res.app.locals.controller.modPacks.get(modPackId);
+	let modPack = res.app.locals.controller.modPacks.getMutable(modPackId);
 	if (!modPack) {
 		res.sendStatus(400);
 		return;
@@ -236,9 +240,9 @@ async function uploadExport(req: Request, res: Response) {
 	let exportFiles = [
 		"export/settings.json",
 		"export/prototypes.json",
-		"export/item-spritesheet.png",
-		"export/item-metadata.json",
 		"export/locale.json",
+		"export/spritesheet.png",
+		"export/metadata.json",
 	];

 	let assets: any = {};
@@ -259,13 +263,19 @@ async function uploadExport(req: Request, res: Response) {
 		await lib.safeOutputFile(path.join("static", `${name}.${hash}${ext}`), await file.async("nodebuffer"));
 	}

-	modPack.exportManifest = new lib.ExportManifest(assets);
+	modPack.exportManifest = new lib.ExportManifest(assets, new Date().toISOString());
 	modPack.fillDefaultSettings(settingPrototypes, logger);
-	res.app.locals.controller.modPacksUpdated([modPack]);
+	res.app.locals.controller.modPacks.set(modPack);

 	res.sendStatus(200);
 }

+type ProxyStreamEvents = {
+	"error": [ err: any ],
+	"close": [],
+	"timeout": [],
+	"source": [],
+}

 export interface ProxyStream {
 	id: string;
@@ -274,7 +284,7 @@ export interface ProxyStream {
 	size?: string;
 	mime?: string;
 	filename: string | null;
-	events: events.EventEmitter;
+	events: events.EventEmitter<ProxyStreamEvents>;
 	timeout: ReturnType<typeof setTimeout>;
 }

@@ -658,6 +668,7 @@ async function uploadMod(req: Request, res: Response) {
 export function addRouteHandlers(app: Application) {
 	app.get("/metrics", (req:Request, res:Response, next:any) => getMetrics(req, res, next).catch(next));
 	app.get("/api/plugins", getPlugins);
+	app.get("/api/cluster-name", getClusterName);
 	app.put("/api/upload-export",
 		validateHostToken,
 		(req:Request, res:Response, next:any) => uploadExport(req, res).catch(next)
@@ -690,4 +701,6 @@ export const webRoutes = [
 	"/roles/:id/view",
 	"/plugins",
 	"/plugins/:name/view",
+	"/icon-reference",
+	"/error",
 ];
@@ -7,6 +7,5 @@
 	"include": [ "web/**/*.tsx", "web/**/*.ts", "package.json" ],
 	"compilerOptions": {
 		"rootDir": "..",
-		"outDir": "dist/browser",
 	}
 }
@@ -4,7 +4,4 @@
 		{ "path": "../lib/tsconfig.node.json" },
 	],
 	"include": ["index.ts", "controller.ts", "package.json", "src/**/*.ts"],
-	"compilerOptions": {
-		"outDir": "dist/node",
-	},
 }
@@ -5,7 +5,7 @@ const { merge } = require("webpack-merge");

 const common = require("@clusterio/web_ui/webpack.common");

-module.exports = (env = {}) => merge(common(env), {
+module.exports = (env = {}, argv = {}) => merge(common(env, argv), {
 	context: __dirname,
 	entry: "./web/index.tsx",
 	devServer: {
@@ -6,16 +6,29 @@ const fs = require("fs-extra");
 const inquirer = require("inquirer");
 const os = require("os");
 const path = require("path");
-const phin = require("phin");
 const stream = require("stream");
 const util = require("util");
 const yargs = require("yargs");

 const { levels, logger, setLogLevel } = require("./logging");
+const { copyPluginTemplates } = require("./template");
 let dev = false;
 const scriptExt = process.platform === "win32" ? ".cmd" : "";
 const finished = util.promisify(stream.finished);
+const { escapeArg } = require("./escape_arg");

+// I hate this, there is a bug with rl.close on windows that was meant to have been fixed in Node14.4
+// See nodejs/node#21771 and nodejs/node#30701 for the apparent fix that was applied
+// One option is to not call rl.close: SBoudrias/Inquirer.js#767
+// But this comes with its own issues: SBoudrias/Inquirer.js#899
+// The solution below was adapted from aws-amplify/amplify-cli#12347
+if (process.platform === "win32") {
+	const _inquirer_close = inquirer.ui.Prompt.prototype.close;
+	inquirer.ui.Prompt.prototype.close = function() {
+		this.rl.terminal = false;
+		_inquirer_close.call(this);
+	};
+}

 const availablePlugins = [
 	{ name: "Global Chat", value: "@clusterio/plugin-global_chat" },
@@ -93,15 +106,25 @@ async function safeOutputFile(file, data, options={}) {
 }

 async function execFile(cmd, args) {
-	logger.verbose(`executing ${cmd} ${args.join(" ")}`);
+	const escaped = args.map(escapeArg);
+	logger.verbose(`executing ${cmd} ${escaped.join(" ")}`);
 	return new Promise((resolve, reject) => {
-		let child = child_process.execFile(cmd, args, (err, stdout, stderr) => {
-			if (err) {
-				reject(err);
-			} else {
-				resolve({ stdout, stderr });
+		let child = child_process.execFile(
+			cmd,
+			escaped,
+			{
+				shell: true,
+
+				env: process.platform === "win32" ? { ...process.env, pct: "%" } : undefined,
+			},
+			(err, stdout, stderr) => {
+				if (err) {
+					reject(err);
+				} else {
+					resolve({ stdout, stderr });
+				}
 			}
-		});
+		);
 		let stdout = new LineSplitter({ readableObjectMode: true });
 		stdout.on("data", line => { logger.verbose(line.toString()); });
 		child.stdout.pipe(stdout);
@@ -312,7 +335,7 @@ async function migrateRename(args) {
 		let mode = "standalone";
 		if (!hasRunSlave) { mode = "controller"; }
 		if (!hasRunMaster) { mode = "host"; }
-		await writeScripts(mode);
+		await writeScripts(mode, "");
 	}

 	logger.info(
@@ -373,7 +396,7 @@ async function installClusterio(mode, plugins) {
 		}
 		for (let plugin of plugins) {
 			if (!pluginList.has(plugin)) {
-				// eslint-disable-next-line node/global-require
+
 				let pluginInfo = require(require.resolve(plugin, { paths: [process.cwd()] })).plugin;
 				pluginList.set(pluginInfo.name, plugin);
 			}
@@ -397,7 +420,7 @@ async function groupIdToName(gid) {
 	}
 }

-async function writeScripts(mode) {
+async function writeScripts(mode, selfSignedCert) {
 	if (["standalone", "controller"].includes(mode)) {
 		if (process.platform === "win32") {
 			await safeOutputFile(
@@ -451,12 +474,13 @@ WantedBy=multi-user.target

 	if (["standalone", "host"].includes(mode)) {
 		if (process.platform === "win32") {
+			let extraCaCertsLine = selfSignedCert ? `set "NODE_EXTRA_CA_CERTS=${selfSignedCert}"\n` : "";
 			await safeOutputFile(
 				"run-host.cmd",
 				`\
@echo off
 set "NODE_OPTIONS=--enable-source-maps %NODE_OPTIONS%"
-:restart
+${extraCaCertsLine}:restart
 call .\\node_modules\\.bin\\clusteriohost.cmd run --can-restart
 if %errorlevel% equ 0 exit /b
 if %errorlevel% equ 8 exit /b
@@ -464,18 +488,20 @@ goto restart
 `
 			);
 		} else {
+			let extraCaCertsLine = selfSignedCert ? `export "NODE_EXTRA_CA_CERTS=${selfSignedCert}"\n` : "";
 			await safeOutputFile(
 				"run-host.sh",
 				`\
 #!/bin/bash
 export "NODE_OPTIONS=--enable-source-maps $NODE_OPTIONS"
-while true; do
+${extraCaCertsLine}while true; do
 	./node_modules/.bin/clusteriohost run --can-restart
 	if [[ $? -eq 0 || $? -eq 8 ]]; then exit $?; fi
 done
 `,
 				{ mode: 0o755 },
 			);
+			extraCaCertsLine = selfSignedCert ? `Environment=NODE_EXTRA_CA_CERTS=${selfSignedCert}\n` : "";
 			await safeOutputFile(
 				"systemd/clusteriohost.service",
 				`\
@@ -489,7 +515,7 @@ WorkingDirectory=${process.cwd()}
 KillMode=mixed
 KillSignal=SIGINT
 Environment=NODE_OPTIONS=--enable-source-maps
-ExecStart=${process.cwd()}/node_modules/.bin/clusteriohost run --log-level=warn --can-restart
+${extraCaCertsLine}ExecStart=${process.cwd()}/node_modules/.bin/clusteriohost run --log-level=warn --can-restart
 Restart=on-failure
 RestartPreventExitStatus=8

@@ -505,6 +531,7 @@ WantedBy=multi-user.target
 async function inquirerMissingArgs(args) {
 	let answers = {};
 	if (args.mode) { answers.mode = args.mode; }
+	if (args["plugin-template"]) { answers.mode = "plugin-template"; }
 	answers = await inquirer.prompt([
 		{
 			type: "list",
@@ -517,6 +544,7 @@ async function inquirerMissingArgs(args) {
 				{ name: "Host only", value: "host" },
 				{ name: "Ctl only", value: "ctl" },
 				{ name: "Plugins only", value: "plugins" },
+				{ name: "Plugin template", value: "plugin-template" },
 			],
 		},
 	], answers);
@@ -536,6 +564,25 @@ async function inquirerMissingArgs(args) {
 				},
 			},
 		], answers);
+
+		if (args.httpPort) { answers.httpPort = args.httpPort; }
+		answers = await inquirer.prompt([
+			{
+				type: "input",
+				name: "httpPort",
+				message: "HTTP port to listen on",
+				default: 8080,
+				validate: input => {
+					if (!input) {
+						return "May not be empty";
+					}
+					if (!Number.isInteger(Number(input))) {
+						return "Must be a number";
+					}
+					return true;
+				},
+			},
+		], answers);
 	}

 	if (answers.mode === "host") {
@@ -579,8 +626,8 @@ async function inquirerMissingArgs(args) {
 			answers.publicAddress = args.publicAddress;
 		} else {
 			try {
-				let result = await phin("https://api.ipify.org/");
-				myIp = result.body.toString();
+				let result = await fetch("https://api.ipify.org/");
+				myIp = await result.text();
 			} catch (err) { /* ignore */ }
 		}
 		answers = await inquirer.prompt([
@@ -644,6 +691,51 @@ async function inquirerMissingArgs(args) {
 		}
 	}

+	if (["standalone", "controller", "host"].includes(answers.mode)) {
+		if (args.hasOwnProperty("remoteNpm")) { answers.remoteNpm = args.remoteNpm; }
+		answers = await inquirer.prompt([
+			{
+				type: "confirm",
+				name: "remoteNpm",
+				message: "Allow remote updates via npm?",
+				default: true,
+			},
+		], answers);
+	}
+
+	if (answers.mode === "plugin-template") {
+		if (args["plugin-template"] && args["plugin-template"].length > 0) {
+			answers.pluginTemplate = args["plugin-template"];
+		}
+		if (args["plugin-name"]) {
+			answers.pluginName = args["plugin-name"];
+		}
+		answers.plugins = [];
+		answers = await inquirer.prompt([
+			{
+				type: "checkbox",
+				name: "pluginTemplate",
+				message: "Plugin templates to use",
+				choices: [
+					{ name: "Controller", value: "controller" },
+					{ name: "Host", value: "host" },
+					{ name: "Instance", value: "instance" },
+					{ name: "Lua Module", value: "module" },
+					{ name: "Command Line", value: "ctl" },
+					{ name: "Web UI", value: "web" },
+					{ name: "No Typescript", value: "js" },
+					{ name: "No Config", value: "no_config" },
+				],
+			},
+			{
+				type: "input",
+				name: "pluginName",
+				message: "Name of your new plugin",
+				default: path.basename(path.resolve()),
+			},
+		], answers);
+	}
+
 	if (dev) {
 		answers.plugins = [];
 	} else if (args.plugins) {
@@ -663,12 +755,16 @@ async function inquirerMissingArgs(args) {
 }

 async function downloadLinuxServer() {
-	let res = await phin("https://factorio.com/get-download/stable/headless/linux64");
+	let res = await fetch("https://factorio.com/get-download/stable/headless/linux64");

-	const url = new URL(res.headers.location);
 	// get the filename of the latest factorio archive from redirected url
+	const url = new URL(res.url); // The res is redirects, need final url
 	const filename = path.posix.basename(url.pathname);
-	const version = filename.match(/(?<=factorio_headless_x64_).*(?=\.tar\.xz)/)[0];
+	const match = filename.match(/(?<=factorio_headless_x64_|factorio-headless_linux_)\d+\.\d+\.\d+(?=\.tar\.xz)/);
+	if (!match || !match.length) {
+		throw Error(`Unable to extract version from filename: ${filename}`);
+	}
+	const version = match[0];

 	const tmpDir = "temp/create-temp/";
 	const archivePath = tmpDir + filename;
@@ -679,17 +775,11 @@ async function downloadLinuxServer() {
 	if (await fs.pathExists(factorioDir)) {
 		logger.warn(`setting downloadDir to ${factorioDir}, but not downloading because already existing`);
 	} else {
-		await fs.ensureDir(tmpDir);
-
-		// follow the redirect
-		res = await phin({
-			url: url.href,
-			stream: true,
-		});
+		await fs.emptyDir(tmpDir);

 		logger.info("Downloading latest Factorio server release. This may take a while.");
 		const writeStream = fs.createWriteStream(tmpArchivePath);
-		res.pipe(writeStream);
+		stream.Readable.fromWeb(res.body).pipe(writeStream);

 		await finished(writeStream);

@@ -704,8 +794,10 @@ async function downloadLinuxServer() {
 			throw e;
 		}

-		await fs.unlink(archivePath);
+		await fs.ensureDir("factorio");
 		await fs.rename(tmpFactorioDir, factorioDir);
+		await fs.unlink(archivePath);
+		await fs.rm(tmpDir);
 	}
 }

@@ -720,7 +812,7 @@ async function main() {
 		})
 		.option("mode", {
 			nargs: 1, describe: "Operating mode to install",
-			choices: ["standalone", "controller", "host", "ctl", "plugins"],
+			choices: ["standalone", "controller", "host", "ctl", "plugins", "plugin-template"],
 		})
 		.option("migrate-rename", {
 			nargs: 0, describe: "Migrate from before slave/master rename", default: false, type: "boolean",
@@ -728,6 +820,13 @@ async function main() {
 		.option("admin", {
 			nargs: 1, describe: "Admin account name [standalone/controller]", type: "string",
 		})
+		.option("http-port", {
+			nargs: 1, describe: "HTTP port to listen on [standalone/controller]", type: "number",
+		})
+		.option("download-headless", {
+			describe: "Download the latest headless release [standalone/controller] [linux only]",
+			type: "boolean", nargs: 0,
+		})
 		.option("host-name", {
 			nargs: 1, describe: "Host name [host]", type: "string",
 		})
@@ -743,9 +842,21 @@ async function main() {
 		.option("factorio-dir", {
 			nargs: 1, describe: "Path to Factorio installation [standalone/host]", type: "string",
 		})
+		.option("self-signed-cert", {
+			nargs: 1, describe: "Path to self-signed certificate of the controller [standalone/host]", type: "string",
+		})
+		.option("remote-npm", {
+			nargs: 0, description: "Allow remote updates via npm [standalone/controller/host]", type: "boolean",
+		})
 		.option("plugins", {
 			array: true, describe: "Plugins to install", type: "string",
 		})
+		.option("plugin-template", {
+			array: true, describe: "Plugin template to use [plugin-template]", type: "string",
+		})
+		.option("plugin-name", {
+			nargs: 1, describe: "Name of your new plugin [plugin-template]", type: "string",
+		})
 		.strict()
 	;

@@ -779,6 +890,13 @@ async function main() {
 	}

 	let answers = await inquirerMissingArgs(args);
+	logger.verbose(JSON.stringify(answers));
+
+	if (answers.pluginTemplate) {
+		await copyPluginTemplates(answers.pluginName, answers.pluginTemplate);
+		return;
+	}
+
 	if (answers.downloadHeadless) {
 		if (answers.factorioDir !== "factorio") {
 			throw new InstallError("--download-headless option requires --factorio-dir to be set to factorio");
@@ -786,8 +904,6 @@ async function main() {
 		await downloadLinuxServer();
 	}

-	logger.verbose(JSON.stringify(answers));
-
 	if (!dev) {
 		await installClusterio(answers.mode, answers.plugins);
 	}
@@ -796,6 +912,9 @@ async function main() {
 	if (["standalone", "controller"].includes(answers.mode)) {
 		logger.info("Setting up controller");
 		await execController(["bootstrap", "create-admin", answers.admin]);
+		await execController(["config", "set", "controller.http_port", answers.httpPort]);
+		await execController(["config", "set", "controller.allow_remote_updates", answers.remoteNpm]);
+		await execController(["config", "set", "controller.allow_plugin_updates", answers.remoteNpm]);
 		let result = await execController(["bootstrap", "generate-user-token", answers.admin]);
 		adminToken = result.stdout.split("\n").slice(-2)[0];
 	}
@@ -810,9 +929,13 @@ async function main() {
 		result = await execController(["bootstrap", "generate-host-token", hostId]);
 		let hostToken = result.stdout.split("\n").slice(-2)[0];

+		// Default to localhost on correct port for host in standalone mode
+		await execHost(["config", "set", "host.controller_url", `http://localhost:${answers.httpPort}/`]);
 		await execHost(["config", "set", "host.controller_token", hostToken]);
 		await execHost(["config", "set", "host.public_address", answers.publicAddress]);
 		await execHost(["config", "set", "host.factorio_directory", answers.factorioDir]);
+		await execHost(["config", "set", "host.allow_remote_updates", answers.remoteNpm]);
+		await execHost(["config", "set", "host.allow_plugin_updates", answers.remoteNpm]);
 	}

 	if (answers.mode === "host") {
@@ -824,11 +947,13 @@ async function main() {
 		await execHost(["config", "set", "host.controller_token", answers.controllerToken]);
 		await execHost(["config", "set", "host.public_address", answers.publicAddress]);
 		await execHost(["config", "set", "host.factorio_directory", answers.factorioDir]);
+		await execHost(["config", "set", "host.allow_remote_updates", answers.remoteNpm]);
+		await execHost(["config", "set", "host.allow_plugin_updates", answers.remoteNpm]);
 	}

 	if (!dev && ["standalone", "controller", "host"].includes(answers.mode)) {
 		logger.info("Writing run scripts");
-		await writeScripts(answers.mode);
+		await writeScripts(answers.mode, args.selfSignedCert);
 	}

 	if (answers.mode === "ctl") {
@@ -0,0 +1,62 @@
+"use strict";
+
+function escapeArg(arg) {
+	// When shell: true is used execFile does not escaping of arguments, they are
+	// simply joined by space and then passed to the shell.
+
+	// For Windows the command is cmd.exe /d /s /c "command arg arg ..."
+	// The parsing and escaping on windows is cursed. The following references are not for mortals:
+	// https://daviddeley.com/autohotkey/parameters/parameters.htm#WIN
+	// https://stackoverflow.com/a/4095133
+	// https://ss64.com/nt/syntax-esc.html
+	if (process.platform === "win32") {
+		if (!/[\t "%&<>\\^|]/.test(arg)) {
+			return arg;
+		}
+
+		const escaped = [];
+		let pos = 0;
+		while (pos < arg.length) {
+			if (arg[pos] === "\\") {
+				// If a backslash is followed by a quote or the end of the string, then
+				// double the number of backslashes because why not!
+				let peek = pos + 1;
+				while (peek !== arg.length && arg[peek] === "\\") {
+					peek += 1;
+				}
+				if (peek === arg.length || arg[peek] === '"') {
+					const count = peek - pos;
+					escaped.push("\\".repeat(count * 2));
+					pos = peek;
+					continue;
+				} else {
+					escaped.push("\\");
+				}
+			} else if (arg[pos] === '"') {
+				escaped.push('""');
+			} else if (arg[pos] === "%") {
+				// Expect a pct environment variable to contain %, because cmd does variable substitutions
+				// before parsing string quotes, and there's no mechanism for escaping % symbols, and this
+				// is a half sane workaround. The less sane workaround is to replace % with %%cd:~,%.
+				escaped.push("%pct%");
+			} else {
+				escaped.push(arg[pos]);
+			}
+			pos += 1;
+		}
+		return `"${escaped.join("")}"`;
+	}
+
+	// For all other platforms the command is /bin/sh -c <command arg arg ...>
+	// The command and its arguments are passed as a single argument to the shell.
+	// See https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02
+
+	if (!/[|&;<>()$`\\"' \t*?\[#~=%]/.test(arg)) {
+		return arg;
+	}
+	return `"${arg.replace(/[$`"\\]/g, "\\$&")}"`;
+}
+
+module.exports = {
+	escapeArg,
+};
@@ -3,23 +3,22 @@
 	"description": "Installer for clusterio",
 	"author": "Hornwitser",
 	"license": "MIT",
-	"version": "2.0.0-alpha.17",
+	"version": "2.0.0-alpha.23",
 	"main": "create.js",
 	"bin": {
 		"clusteriocreate": "./create.js"
 	},
 	"keywords": [
-		"factorio",
-		"clusterio"
+		"clusterio",
+		"factorio"
 	],
 	"engines": {
-		"node": ">=18"
+		"node": ">=20"
 	},
 	"dependencies": {
-		"chalk": "^4.1.2",
-		"fs-extra": "^11.1.1",
+		"chalk": "catalog:",
+		"fs-extra": "catalog:",
 		"inquirer": "^8.2.4",
-		"phin": "^3.7.0",
 		"yargs": "^17.7.2"
 	},
 	"publishConfig": {
@@ -0,0 +1,202 @@
+"use strict";
+const { logger } = require("./logging");
+const fs = require("fs-extra");
+const path = require("path");
+
+const _package = require("./package.json");
+
+async function copyTemplateFile(src, dst, properties) {
+	logger.verbose(`Writing ${dst} from template ${src}`);
+
+	// Closure, get the property value or throw
+	function getProperty(property) {
+		if (!properties.hasOwnProperty(property)) {
+			throw new Error(`Unknown property (${property}) found in template file ${src}`);
+		}
+
+		return properties[property];
+	}
+
+	// Closure, Get the boolean conjunction of a set of properties
+	function propertyConjunction(props) {
+		for (const property of props) {
+			if (property.startsWith("!")) {
+				if (Boolean(getProperty(property.slice(1)))) {
+					return false;
+				}
+			} else if (!Boolean(getProperty(property))) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+
+	// Process the the template file
+	const badChars = /[\(\)-+/*<>=]/;
+	const templateData = await fs.readFile(src, "utf8");
+	const outputData = templateData
+		// match preprocessor comments: //%//
+		.replace(/^\/\/%\/\/.*\n/gm, "")
+		// match preprocessor insert: __property__
+		.replace(/__([a-zA-Z][a-zA-Z0-9_]*?[a-zA-Z0-9]?)__/gm, (_, property) => getProperty(property))
+		// match preprocessor conditionals: //%if <CONDITION> [// COMMENT]\n <CONTENT> \n//%endif [COMMENT]\n
+		.replace(/^\/\/%if ([^\n\/]*)(?:\/\/.*?)?\n((?:.|\n)*?)\/\/%endif.*\n/gm, (_, condition, content) => {
+			let include = false;
+			const conjunctions = condition.split("|");
+			for (const conjunct of conjunctions) {
+				if (badChars.test(conjunct)) {
+					throw new Error("Preprocessor condition can only contain logical operators" +
+						"such as & | or ! it can not have arithmetic, comparisons or parenthesis"
+					);
+				}
+
+				const property_names = conjunct.split("&").map(s => s.trim());
+				if (propertyConjunction(property_names)) {
+					include = true;
+					break;
+				}
+			}
+
+			return include ? content : "";
+		});
+
+	// Attempt to write the output file, warn if it already exists
+	try {
+		await fs.outputFile(dst, outputData, { flag: "wx" });
+	} catch (err) {
+		if (err.code === "EEXIST") {
+			logger.warn(`Could not create file ${dst} because it already exists`);
+		} else {
+			throw err;
+		}
+	}
+}
+
+async function copyPluginTemplates(pluginName, templates) {
+	logger.info(`Please wait, coping templates for ${templates.join(", ")}`);
+	const files = new Map();
+	const prepare = [];
+
+	// Some basic flags for selecting files to include
+	const javascriptOnly = templates.includes("js");
+	const config = !templates.includes("no_config") && templates.some(value => (
+		["controller", "host", "instance", "ctl"].includes(value)
+	));
+	const webpack = config || templates.includes("controller") || templates.includes("web");
+
+	// A count of the number of isolated contexts the plugin runs under
+	let pluginContexts = 0;
+
+	// Get the file extension and path to the templates
+	const ext = javascriptOnly ? "js" : "ts";
+	const templatePath = path.resolve(__dirname, javascriptOnly ? "./templates/plugin-js" : "./templates/plugin-ts");
+	const commonPath = path.resolve(__dirname, "./templates/common");
+
+	// Files included in all templates
+	files.set(".gitignore", path.join(commonPath, "template.gitignore"));
+	files.set(".npmignore", path.join(commonPath, "template.npmignore"));
+	files.set("package.json", path.join(commonPath, "package.json"));
+	files.set(`index.${ext}`, path.join(templatePath, `index.${ext}`));
+
+	// Files and dependencies to support typescript
+	if (!javascriptOnly) {
+		prepare.push("tsc --build");
+		files.set("tsconfig.json", path.join(templatePath, "tsconfig.json"));
+		files.set("tsconfig.node.json", path.join(templatePath, "tsconfig.node.json"));
+		files.set("tsconfig.base.json", path.join(templatePath, "tsconfig.base.json"));
+		if (webpack) {
+			files.set("tsconfig.browser.json", path.join(templatePath, "tsconfig.browser.json"));
+		}
+	}
+
+	// Files and dependences to support webpack
+	if (webpack) {
+		prepare.push("webpack-cli --mode production");
+		files.set("webpack.config.js", path.join(commonPath, "webpack.config.js"));
+		if (templates.includes("web")) {
+			files.set(`web/index.${ext}x`, path.join(templatePath, `web/plugin.${ext}x`));
+			pluginContexts += 1;
+		} else {
+			files.set(`web/index.${ext}x`, path.join(templatePath, `web/no_plugin.${ext}x`));
+		}
+	}
+
+	// Files for the controller
+	if (templates.includes("controller")) {
+		files.set(`controller.${ext}`, path.join(templatePath, `controller.${ext}`));
+		pluginContexts += 1;
+	}
+
+	// Files for hosts
+	if (templates.includes("host")) {
+		files.set(`host.${ext}`, path.join(templatePath, `host.${ext}`));
+		pluginContexts += 1;
+	}
+
+	// Files for instances
+	if (templates.includes("instance")) {
+		files.set(`instance.${ext}`, path.join(templatePath, `instance.${ext}`));
+		pluginContexts += 1;
+	}
+
+	// Files for lua modules
+	if (templates.includes("module")) {
+		files.set("module/module.json", path.join(commonPath, "module/module.json"));
+		files.set("module/control.lua", path.join(commonPath, "module/control.lua"));
+		files.set("module/module_exports.lua", path.join(commonPath, "module/module_exports.lua"));
+		if (templates.includes("instance")) {
+			files.set("module/globals.lua", path.join(commonPath, "module/globals.lua"));
+		} else {
+			files.set(`instance.${ext}`, path.join(templatePath, `instance_empty.${ext}`));
+		}
+	}
+
+	// Files for the control tool
+	if (templates.includes("ctl")) {
+		files.set(`ctl.${ext}`, path.join(templatePath, `ctl.${ext}`));
+		pluginContexts += 1;
+	}
+
+	// If there are more than one contexts then include the message file
+	if (pluginContexts > 1) {
+		files.set(`messages.${ext}`, path.join(templatePath, `messages.${ext}`));
+	}
+
+	// Properties that will control the replacements in the templates
+	const properties = {
+		// Weather this is ts or js
+		typescript: !javascriptOnly,
+		ext: ext,
+		// Which templates where requested
+		multi_context: pluginContexts > 1,
+		controller: templates.includes("controller"),
+		host: templates.includes("host"),
+		instance: templates.includes("instance"),
+		module: templates.includes("module"),
+		ctl: templates.includes("ctl"),
+		web: templates.includes("web"),
+		// Macro flags for context requirements
+		webpack: webpack,
+		config: config,
+		// String values for package json
+		clusterio_version: _package.version,
+		node_version: _package.engines.node,
+		prepare: prepare.join(" && "),
+		plugin_name: pluginName,
+	};
+
+	// Write all the template files
+	const writes = [];
+	for (let [dst, src] of files) {
+		writes.push(copyTemplateFile(src, dst, properties));
+	}
+
+	// Wait for writes to complete
+	await Promise.all(writes);
+	logger.info("Successfully wrote all template files");
+}
+
+module.exports = {
+	copyPluginTemplates,
+};
@@ -0,0 +1,93 @@
+--[[
+The 'control' file within factorio is used as the entry point for mods, in Clusterio this is only a convention
+You can change which files are loaded (exports event handlers) and required (no events) by Clusterio within module.json
+It is highly advised to use FMTK (justarandomgeek.factoriomod-debug) when writing Lua code for factorio
+Most of your code will be within this one file, but you can create more and require them
+
+clusterio_api exposes functions to enable communication with your InstancePlugin 
+compat exposes shims to simplify compatibly between factorio versions, use the following to require 2.0
+`assert(compat.version_ge("2.0.0"), "__plugin_name__ requires factorio 2.0")`
+]]
+
+local clusterio_api = require("modules/clusterio/api")
+local compat = require("modules/clusterio/compat")
+
+--- Top level module table, contains event handlers and public methods
+--- @class __plugin_name__
+local MyModule = {
+}
+
+--[[
+`compat.script_data` persists between restarts and is shared between modules, therefore you should use your plugin name to avoid conflicts
+The following helper function is desync safe and avoids name conflicts after being called during `clusterio_api.events.on_server_startup`
+There are edge cases in the following events: pre player left, player left, console command, and config changed
+If you use any of these events and access `script_data` then make sure to call this function first
+]]
+local script_data = {}
+local function setup_script_data()
+	if compat.script_data["__plugin_name__"] == nil then
+		compat.script_data["__plugin_name__"] = {
+			-- starting values go here
+		}
+	end
+	MyModule.on_load()
+end
+
+--- The on_load function is called independently for each client when they first load the map
+-- It should be used to restore global aliases and metatables not registered with script.register_metatable
+function MyModule.on_load()
+	script_data = compat.script_data["__plugin_name__"]
+end
+
+--- Public methods should be available though your top level module table
+function MyModule.foo()
+	game.print("foo: " .. (script_data.counter or 0))
+end
+
+--- Private methods should be local to the file, this will prevent others from calling it
+local function bar()
+	script_data.counter = (script_data.counter or 0) + 1
+	game.print("bar: " .. script_data.counter)
+end
+
+--- Clusterio provides a few custom events, on_server_startup is the most useful and should be used in place of on_init
+--- @param event EventData.on_server_startup
+local function on_server_startup(event)
+	setup_script_data()
+	game.print(compat.table_to_json(event))
+end
+
+--- Triggered every time a player crafts an item, see below for how handlers are registered
+--- @param event EventData.on_player_crafted_item
+local function on_player_crafted_item(event)
+	game.print(compat.table_to_json(event))
+//%if instance
+	local player = assert(game.get_player(event.player_index))
+	clusterio_api.send_json("__plugin_name__-plugin_example_ipc", {
+		tick = game.tick, player_name = player.name
+	})
+//%endif
+end
+
+--- Run bar every 5 seconds, see below for how handlers are registered
+local function on_nth_tick_300()
+	game.print(game.tick)
+	bar()
+end
+
+--- Factorio events are accessible through defines.events, you can have one handler per event per file
+local e = defines.events
+local events = {
+	[clusterio_api.events.on_server_startup] = on_server_startup,
+	[e.on_player_crafted_item] = on_player_crafted_item,
+}
+
+--- Nth tick is a special case that requires its own table, the index represents the time period between calls in ticks
+local on_nth_tick = {
+	[300] = on_nth_tick_300,
+}
+
+--- Always return the top level module table from control, this is how Clusterio will access your event handlers
+MyModule.events = events --- @package
+MyModule.on_nth_tick = on_nth_tick --- @package
+return MyModule
@@ -0,0 +1,9 @@
+--[[
+It is best practice to not expose any globals because all modules share a global environment
+However, sometimes you need globals, for example to access functions within rcon commands
+Therefore, we advise that this should be the only file in your module to expose globals
+Typically this would be your control file as shown in the example below
+]]
+
+-- Access using `/sc __plugin_name__.foo()`
+__plugin_name__ = require("modules/__plugin_name__/control")
@@ -0,0 +1,14 @@
+{
+	"name": "__plugin_name__",
+	"load": [
+		"control.lua"
+	],
+	"require": [
+//%if instance
+		"globals.lua"
+//%endif
+	],
+	"dependencies": {
+		"clusterio": "*"
+	}
+}
@@ -0,0 +1,8 @@
+--[[
+It is typical for a module to have a control file as the entry point, although this is not a requirement
+Therefore, Clusterio allows you to specify a single default export that can be accessed by other modules
+You are not required to specify any default export, but note that a module can still require yours directly
+]]
+
+-- Access using `local __plugin_name__ = require("modules/__plugin_name__")`
+return require("modules/__plugin_name__/control")
@@ -0,0 +1,77 @@
+{
+	"name": "__plugin_name__",
+	"version": "0.1.0",
+	"description": "Example Description. Package. Change me in package.json",
+//%if typescript
+	"main": "dist/node/index.js",
+//%endif
+//%if !typescript
+	"main": "index.js",
+//%endif
+	"scripts": {
+		"prepare": "__prepare__"
+	},
+	"engines": {
+		"node": "__node_version__"
+	},
+	"peerDependencies": {
+//%if controller
+		"@clusterio/controller": "^__clusterio_version__",
+//%endif
+//%if webpack
+		"@clusterio/web_ui": "^__clusterio_version__",
+//%endif
+//%if host
+		"@clusterio/host": "^__clusterio_version__",
+//%endif
+//%if ctl
+		"@clusterio/ctl": "^__clusterio_version__",
+//%endif
+		"@clusterio/lib": "^__clusterio_version__"
+	},
+	"devDependencies": {
+//%// Typescript and type declarations
+//%if typescript
+		"typescript": "^5.5.3",
+		"@types/node": "^20.4.5",
+//%endif
+//%if typescript & web
+		"@types/react": "^18.2.21",
+//%endif
+//%// Everything else
+//%if web
+		"antd": "^5.13.0",
+		"react": "^18.2.0",
+		"react-dom": "^18.2.0",
+//%endif
+//%if webpack
+		"webpack": "^5.88.2",
+		"webpack-cli": "^5.1.4",
+		"webpack-merge": "^5.9.0",
+//%endif
+//%if controller
+		"@clusterio/controller": "^__clusterio_version__",
+//%endif
+//%if webpack
+		"@clusterio/web_ui": "^__clusterio_version__",
+//%endif
+//%if host
+		"@clusterio/host": "^__clusterio_version__",
+//%endif
+//%if ctl
+		"@clusterio/ctl": "^__clusterio_version__",
+//%endif
+		"@clusterio/lib": "^__clusterio_version__"
+	},
+	"dependencies": {
+		"@sinclair/typebox": "^0.30.4"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"keywords": [
+		"clusterio",
+		"clusterio-plugin",
+		"factorio"
+	]
+}
@@ -0,0 +1,2 @@
+node_modules/
+dist/
@@ -0,0 +1,3 @@
+webpack.config.js
+dist/browser
+dist/web
@@ -0,0 +1,34 @@
+"use strict";
+const path = require("path");
+const webpack = require("webpack");
+const { merge } = require("webpack-merge");
+
+const common = require("@clusterio/web_ui/webpack.common");
+
+module.exports = (env = {}, argv = {}) => merge(common(env, argv), {
+	context: __dirname,
+	entry: "./web/index.__ext__x",
+	output: {
+		path: path.resolve(__dirname, "dist", "web"),
+	},
+	plugins: [
+		new webpack.container.ModuleFederationPlugin({
+			name: "__plugin_name__",
+			library: { type: "window", name: "plugin___plugin_name__" },
+			exposes: {
+				"./": "./index.__ext__",
+				"./package.json": "./package.json",
+				"./web": "./web/index.__ext__x",
+			},
+			shared: {
+				"@clusterio/lib": { import: false },
+				"@clusterio/web_ui": { import: false },
+//%if web
+				"antd": { import: false },
+				"react": { import: false },
+				"react-dom": { import: false },
+//%endif
+			},
+		}),
+	],
+});
@@ -0,0 +1,85 @@
+"use strict";
+const lib = require("@clusterio/lib");
+const { BaseControllerPlugin } = require("@clusterio/controller");
+//%if multi_context // Messages requires multi context
+
+const {
+	PluginExampleEvent, PluginExampleRequest,
+//%endif
+//%if controller & web // Subscribing requires web content and the controller
+	ExampleSubscribableUpdate, ExampleSubscribableValue,
+//%endif
+//%if multi_context // Messages requires multi context
+} = require("./messages");
+//%endif
+
+class ControllerPlugin extends BaseControllerPlugin {
+//%if controller & web // Subscribing requires web content and the controller
+	exampleDatabase;
+	storageDirty = false;
+
+//%endif
+//%if multi_context // Subscribing requires multi context
+	async init() {
+		this.controller.handle(PluginExampleEvent, this.handlePluginExampleEvent.bind(this));
+		this.controller.handle(PluginExampleRequest, this.handlePluginExampleRequest.bind(this));
+//%endif
+//%if controller & web // Subscribing requires web content and the controller
+		this.controller.subscriptions.handle(ExampleSubscribableUpdate, this.handleExampleSubscription.bind(this));
+		// If needed, replace with loading from database file such as lib.Datastore
+		this.exampleDatabase = new Map([["foo", new ExampleSubscribableValue("foo", 0, false)]]);
+//%endif
+//%if multi_context // Subscribing requires multi context
+	}
+//%endif
+
+	async onControllerConfigFieldChanged(field, curr, prev) {
+		this.logger.info(`controller::onControllerConfigFieldChanged ${field}`);
+	}
+//%if instance
+
+	async onInstanceConfigFieldChanged(instance, field, curr, prev) {
+		this.logger.info(`controller::onInstanceConfigFieldChanged ${instance.id} ${field}`);
+	}
+//%endif
+
+	async onSaveData() {
+		this.logger.info("controller::onSaveData");
+	}
+
+	async onShutdown() {
+		this.logger.info("controller::onShutdown");
+	}
+
+	async onPlayerEvent(instance, event) {
+		this.logger.info(`controller::onPlayerEvent ${instance.id} ${JSON.stringify(event)}`);
+	}
+//%if multi_context
+
+	async handlePluginExampleEvent(event) {
+		this.logger.info(JSON.stringify(event));
+	}
+
+	async handlePluginExampleRequest(request) {
+		this.logger.info(JSON.stringify(request));
+		return {
+			myResponseString: request.myString,
+			myResponseNumbers: request.myNumberArray,
+		};
+	}
+//%endif
+//%if controller & web // Subscribing requires web content and the controller
+
+	async handleExampleSubscription(request) {
+		this.logger.info(JSON.stringify(request));
+		const values = [...this.exampleDatabase.values()].filter(
+			value => value.updatedAtMs > request.lastRequestTimeMs,
+		);
+		return values.length ? new ExampleSubscribableUpdate(values) : null;
+	}
+//%endif
+}
+
+module.exports = {
+	ControllerPlugin,
+};
@@ -0,0 +1,32 @@
+"use strict";
+const { BaseCtlPlugin } = require("@clusterio/ctl");
+const { CommandTree, Command } = require("@clusterio/lib");
+//%// We do not check for multi context here because it doesn't make sense to have a ctl without messages
+const { PluginExampleEvent, PluginExampleRequest } = require("./messages");
+/* eslint-disable no-console */
+
+const pluginCommands = new CommandTree({
+	name: "__plugin_name__", description: "The default description I forgot to change",
+});
+
+pluginCommands.add(new Command({
+	definition: ["my-command <foo>", "My command description that I really should change", (yargs) => {
+		yargs.positional("foo", { describe: "foo is foo!", type: "string" });
+	}],
+	handler: async function(args, control) {
+		const response = await control.sendTo("controller", new PluginExampleRequest(args.foo, [1, 2, 3]));
+		console.log(response);
+		console.log(args);
+	},
+}));
+
+/* eslint-enable no-console */
+class CtlPlugin extends BaseCtlPlugin {
+	async addCommands(rootCommand) {
+		rootCommand.add(pluginCommands);
+	}
+}
+
+module.exports = {
+	CtlPlugin,
+};
@@ -0,0 +1,41 @@
+"use strict";
+const lib = require("@clusterio/lib");
+const { BaseHostPlugin } = require("@clusterio/host");
+//%if multi_context
+const { PluginExampleEvent, PluginExampleRequest } = require("./messages");
+//%endif
+
+class HostPlugin extends BaseHostPlugin {
+//%if multi_context
+	async init() {
+		this.host.handle(PluginExampleEvent, this.handlePluginExampleEvent.bind(this));
+		this.host.handle(PluginExampleRequest, this.handlePluginExampleRequest.bind(this));
+	}
+//%endif
+
+	async onHostConfigFieldChanged(field, curr, prev) {
+		this.logger.info(`host::onInstanceConfigFieldChanged ${field}`);
+	}
+
+	async onShutdown() {
+		this.logger.info("host::onShutdown");
+	}
+//%if multi_context
+
+	async handlePluginExampleEvent(event) {
+		this.logger.info(JSON.stringify(event));
+	}
+
+	async handlePluginExampleRequest(request) {
+		this.logger.info(JSON.stringify(request));
+		return {
+			myResponseString: request.myString,
+			myResponseNumbers: request.myNumberArray,
+		};
+	}
+//%endif
+}
+
+module.exports = {
+	HostPlugin,
+};
@@ -0,0 +1,130 @@
+"use strict";
+const lib = require("@clusterio/lib");
+//%if multi_context
+const Messages = require("./messages");
+
+lib.definePermission({
+	name: "__plugin_name__.example.permission.event",
+	title: "Example permission event",
+	description: "Example Description. Event. Change me in index.js",
+	grantByDefault: true,
+});
+
+lib.definePermission({
+	name: "__plugin_name__.example.permission.request",
+	title: "Example permission request",
+	description: "Example Description. Request. Change me in index.js",
+	grantByDefault: true,
+});
+//%endif
+//%if controller & web // Subscribing requires web content and the controller
+
+lib.definePermission({
+	name: "__plugin_name__.example.permission.subscribe",
+	title: "Example permission subscribe",
+	description: "Example Description. Subscribe. Change me in index.js",
+	grantByDefault: true,
+});
+//%endif
+//%if web
+
+lib.definePermission({
+	name: "__plugin_name__.page.view",
+	title: "Example page view permission",
+	description: "Example Description. View. Change me in index.js",
+	grantByDefault: true,
+});
+//%endif
+
+const plugin = {
+	name: "__plugin_name__",
+	title: "__plugin_name__",
+	description: "Example Description. Plugin. Change me in index.js",
+//%if controller | host & !config | instance & !config | ctl & !config // Blank line for formatting
+
+//%endif
+//%if controller
+	controllerEntrypoint: "./dist/node/controller",
+//%endif
+//%if controller & config
+	controllerConfigFields: {
+		"__plugin_name__.myControllerField": {
+			title: "My Controller Field",
+			description: "This should be removed from index.js",
+			type: "string",
+			initialValue: "Remove Me",
+		},
+	},
+//%endif
+//%if host & config // Blank line for formatting
+
+//%endif
+//%if host
+	hostEntrypoint: "./dist/node/host",
+//%endif
+//%if host & config
+	hostConfigFields: {
+		"__plugin_name__.myHostField": {
+			title: "My Host Field",
+			description: "This should be removed from index.js",
+			type: "string",
+			initialValue: "Remove Me",
+		},
+	},
+//%endif
+//%if instance & config | module & config // Blank line for formatting
+
+//%endif
+//%if instance | module // Modules load an empty instance plugin
+	instanceEntrypoint: "./dist/node/instance",
+//%endif
+//%if instance & config
+	instanceConfigFields: {
+		"__plugin_name__.myInstanceField": {
+			title: "My Instance Field",
+			description: "This should be removed from index.js",
+			type: "string",
+			initialValue: "Remove Me",
+		},
+	},
+//%endif
+//%if ctl & config // Blank line for formatting
+
+//%endif
+//%if ctl
+	ctlEntrypoint: "./dist/node/ctl",
+//%endif
+//%if ctl & config
+	controlConfigFields: {
+		"__plugin_name__.myControlField": {
+			title: "My Control Field",
+			description: "This should be removed from index.js",
+			type: "string",
+			initialValue: "Remove Me",
+		},
+	},
+//%endif
+//%if multi_context // Subscribing requires multi context
+
+	messages: [
+		Messages.PluginExampleEvent,
+		Messages.PluginExampleRequest,
+//%endif
+//%if controller & web // Subscribing requires web content and the controller
+		Messages.ExampleSubscribableUpdate,
+//%endif
+//%if multi_context // Subscribing requires multi context
+	],
+//%endif
+//%if web // Web content template has an example route which is the plugin name
+
+	webEntrypoint: "./web",
+	routes: [
+		"/__plugin_name__",
+	],
+//%endif
+};
+
+module.exports = {
+	plugin,
+};
@@ -0,0 +1,74 @@
+"use strict";
+const lib = require("@clusterio/lib");
+const { BaseInstancePlugin } = require("@clusterio/host");
+//%if multi_context
+const { PluginExampleEvent, PluginExampleRequest } = require("./messages");
+//%endif
+
+class InstancePlugin extends BaseInstancePlugin {
+//%if multi_context | module
+	async init() {
+//%if multi_context
+		this.instance.handle(PluginExampleEvent, this.handlePluginExampleEvent.bind(this));
+		this.instance.handle(PluginExampleRequest, this.handlePluginExampleRequest.bind(this));
+//%endif
+//%if module
+		this.instance.server.handle("__plugin_name__-plugin_example_ipc", this.handlePluginExampleIPC.bind(this));
+//%endif
+//%if multi_context | module
+	}
+//%endif
+
+	async onInstanceConfigFieldChanged(field, curr, prev) {
+		this.logger.info(`instance::onInstanceConfigFieldChanged ${field}`);
+	}
+
+	async onStart() {
+		// Called once rcon becomes available
+		this.logger.info("instance::onStart");
+	}
+
+	async onStop() {
+		// Called during normal exits before rcon becomes unavailable
+		this.logger.info("instance::onStop");
+	}
+
+	onExit() {
+		// Called during all exits, including crashes and init failures, rcon is not available
+		this.logger.info("instance::onExit");
+	}
+
+
+	async onPlayerEvent(event) {
+		this.logger.info(`onPlayerEvent::onPlayerEvent ${JSON.stringify(event)}`);
+//%if module
+		if (this.instance.status === "running") {
+			await this.sendRcon("/sc __plugin_name__.foo()");
+		}
+//%endif
+	}
+//%if multi_context
+
+	async handlePluginExampleEvent(event) {
+		this.logger.info(JSON.stringify(event));
+	}
+
+	async handlePluginExampleRequest(request) {
+		this.logger.info(JSON.stringify(request));
+		return {
+			myResponseString: request.myString,
+			myResponseNumbers: request.myNumberArray,
+		};
+	}
+//%endif
+//%if module
+
+	async handlePluginExampleIPC(event) {
+		this.logger.info(JSON.stringify(event));
+	}
+//%endif
+}
+
+module.exports = {
+	InstancePlugin,
+};
@@ -0,0 +1,11 @@
+"use strict";
+const { BaseInstancePlugin } = require("@clusterio/host");
+
+class InstancePlugin extends BaseInstancePlugin {
+	// This class is empty because an instance plugin must be defined for a module to be injected
+	// This requirement may change in the future to allow for standalone modules
+}
+
+module.exports = {
+	InstancePlugin,
+};
@@ -0,0 +1,101 @@
+"use strict";
+const { plainJson, jsonArray, JsonBoolean, JsonNumber, JsonString, StringEnum } = require("@clusterio/lib");
+const { Type } = require("@sinclair/typebox");
+
+class PluginExampleEvent {
+	static type = "event";
+	static src = ["host", "control"];
+	static dst = ["controller", "host", "instance"];
+	static plugin = "__plugin_name__";
+	static permission = "__plugin_name__.example.permission.event";
+
+	constructor(myString, myNumberArray) {
+		this.myString = myString;
+		this.myNumberArray = myNumberArray;
+	}
+
+	static jsonSchema = Type.Object({
+		"myString": Type.String(),
+		"myNumberArray": Type.Array(Type.Number()),
+	});
+
+	static fromJSON(json) {
+		return new PluginExampleEvent(json.myString, json.myNumberArray);
+	}
+}
+
+class PluginExampleRequest {
+	static type = "request";
+	static src = ["host", "control"];
+	static dst = ["controller", "host", "instance"];
+	static plugin = "__plugin_name__";
+	static permission = "__plugin_name__.example.permission.request";
+
+	constructor(myString, myNumberArray) {
+		this.myString = myString;
+		this.myNumberArray = myNumberArray;
+	}
+
+	static jsonSchema = Type.Object({
+		"myString": Type.String(),
+		"myNumberArray": Type.Array(Type.Number()),
+	});
+
+	static fromJSON(json) {
+		return new PluginExampleRequest(json.myString, json.myNumberArray);
+	}
+
+	static Response = plainJson(Type.Object({
+		"myResponseString": Type.String(),
+		"myResponseNumbers": Type.Array(Type.Number()),
+	}));
+}
+//%if controller & web // Subscribing requires web content and the controller
+
+class ExampleSubscribableValue {
+	constructor(id, updatedAtMs, isDeleted) {
+		this.id = id;
+		this.updatedAtMs = updatedAtMs;
+		this.isDeleted = isDeleted;
+	}
+
+	static jsonSchema = Type.Object({
+		id: Type.String(),
+		updatedAtMs: Type.Number(),
+		isDeleted: Type.Boolean(),
+	});
+
+	static fromJSON(json) {
+		return new this(json.id, json.updatedAtMs, json.isDeleted);
+	}
+}
+
+class ExampleSubscribableUpdate {
+	static type = "event";
+	static src = "controller";
+	static dst = "control";
+	static plugin = "__plugin_name__";
+	static permission = "__plugin_name__.example.permission.subscribe";
+
+	constructor(updates) {
+		this.updates = updates;
+	}
+
+	static jsonSchema = Type.Object({
+		"updates": Type.Array(ExampleSubscribableValue.jsonSchema),
+	});
+
+	static fromJSON(json) {
+		return new this(json.updates.map(update => ExampleSubscribableValue.fromJSON(update)));
+	}
+}
+//%endif
+
+module.exports = {
+	PluginExampleEvent,
+	PluginExampleRequest,
+//%if controller & web // Subscribing requires web content and the controller
+	ExampleSubscribableValue,
+	ExampleSubscribableUpdate,
+//%endif
+};
@@ -0,0 +1,93 @@
+import React, {
+	useContext, useEffect, useState,
+//%if controller // Subscribing requires web content and the controller
+	useCallback, useSyncExternalStore,
+//%endif
+} from "react";
+
+// import {
+//
+// } from "antd";
+
+import {
+	BaseWebPlugin, PageLayout, PageHeader, Control, ControlContext, notifyErrorHandler,
+} from "@clusterio/web_ui";
+//%if multi_context // Messages requires multi context
+
+import {
+	PluginExampleEvent, PluginExampleRequest,
+//%endif
+//%if controller // Subscribing requires web content and the controller
+	ExampleSubscribableUpdate, ExampleSubscribableValue,
+//%endif
+//%if multi_context // Messages requires multi context
+} from "../messages";
+//%endif
+
+import * as lib from "@clusterio/lib";
+
+function MyTemplatePage() {
+	let control = useContext(ControlContext);
+//%if controller // Subscribing requires web content and the controller
+	const plugin = control.plugins.get("__plugin_name__");
+	const [subscribableData, synced] = plugin.useSubscribableData();
+//%endif
+
+	return <PageLayout nav={[{ name: "__plugin_name__" }]}>
+		<PageHeader title="__plugin_name__" />
+//%if controller // Subscribing requires web content and the controller
+		Synced: {String(synced)} Data: {JSON.stringify([...subscribableData.values()])}
+//%endif
+	</PageLayout>;
+}
+
+export class WebPlugin extends BaseWebPlugin {
+//%if controller // Subscribing requires web content and the controller
+	subscribableData = new lib.EventSubscriber(ExampleSubscribableUpdate, this.control);
+
+//%endif
+	async init() {
+		this.pages = [
+			{
+				path: "/__plugin_name__",
+				sidebarName: "__plugin_name__",
+				// This permission is client side only, so it must match the permission string of a resource request to be secure
+				// An undefined value means that the page will always be visible
+//%if controller // Subscribing requires web content and the controller
+				permission: "__plugin_name__.example.permission.subscribe",
+//%endif
+//%if !controller
+				permission: "__plugin_name__.example.permission.view",
+//%endif
+				content: <MyTemplatePage/>,
+			},
+		];
+//%if multi_context
+
+		this.control.handle(PluginExampleEvent, this.handlePluginExampleEvent.bind(this));
+		this.control.handle(PluginExampleRequest, this.handlePluginExampleRequest.bind(this));
+//%endif
+	}
+//%if controller// Subscribing requires web content and the controller
+
+	useSubscribableData() {
+		const control = useContext(ControlContext);
+		const subscribe = useCallback((callback) => this.subscribableData.subscribe(callback), [control]);
+		return useSyncExternalStore(subscribe, () => this.subscribableData.getSnapshot());
+	}
+//%endif
+//%if multi_context
+
+	async handlePluginExampleEvent(event) {
+		this.logger.info(JSON.stringify(event));
+	}
+
+	async handlePluginExampleRequest(request) {
+		this.logger.info(JSON.stringify(request));
+		return {
+			myResponseString: request.myString,
+			myResponseNumbers: request.myNumberArray,
+		};
+	}
+//%endif
+}
@@ -0,0 +1,80 @@
+import * as lib from "@clusterio/lib";
+import { BaseControllerPlugin, InstanceRecord } from "@clusterio/controller";
+//%if multi_context // Messages requires multi context
+
+import {
+	PluginExampleEvent, PluginExampleRequest,
+//%endif
+//%if controller & web // Subscribing requires web content and the controller
+	ExampleSubscribableUpdate, ExampleSubscribableValue,
+//%endif
+//%if multi_context // Messages requires multi context
+} from "./messages";
+//%endif
+
+export class ControllerPlugin extends BaseControllerPlugin {
+//%if controller & web // Subscribing requires web content and the controller
+	exampleDatabase!: Map<string, ExampleSubscribableValue>;
+	storageDirty = false;
+
+//%endif
+//%if multi_context // Subscribing requires multi context
+	async init() {
+		this.controller.handle(PluginExampleEvent, this.handlePluginExampleEvent.bind(this));
+		this.controller.handle(PluginExampleRequest, this.handlePluginExampleRequest.bind(this));
+//%endif
+//%if controller & web // Subscribing requires web content and the controller
+		this.controller.subscriptions.handle(ExampleSubscribableUpdate, this.handleExampleSubscription.bind(this));
+		// If needed, replace with loading from database file such as lib.Datastore
+		this.exampleDatabase = new Map([["foo", new ExampleSubscribableValue("foo", 0, false)]]);
+//%endif
+//%if multi_context // Subscribing requires multi context
+	}
+//%endif
+
+	async onControllerConfigFieldChanged(field: string, curr: unknown, prev: unknown) {
+		this.logger.info(`controller::onControllerConfigFieldChanged ${field}`);
+	}
+//%if instance
+
+	async onInstanceConfigFieldChanged(instance: InstanceRecord, field: string, curr: unknown, prev: unknown) {
+		this.logger.info(`controller::onInstanceConfigFieldChanged ${instance.id} ${field}`);
+	}
+//%endif
+
+	async onSaveData() {
+		this.logger.info("controller::onSaveData");
+	}
+
+	async onShutdown() {
+		this.logger.info("controller::onShutdown");
+	}
+
+	async onPlayerEvent(instance: InstanceRecord, event: lib.PlayerEvent) {
+		this.logger.info(`controller::onPlayerEvent ${instance.id} ${JSON.stringify(event)}`);
+	}
+//%if multi_context
+
+	async handlePluginExampleEvent(event: PluginExampleEvent) {
+		this.logger.info(JSON.stringify(event));
+	}
+
+	async handlePluginExampleRequest(request: PluginExampleRequest) {
+		this.logger.info(JSON.stringify(request));
+		return {
+			myResponseString: request.myString,
+			myResponseNumbers: request.myNumberArray,
+		};
+	}
+//%endif
+//%if controller & web // Subscribing requires web content and the controller
+
+	async handleExampleSubscription(request: lib.SubscriptionRequest) {
+		this.logger.info(JSON.stringify(request));
+		const values = [...this.exampleDatabase.values()].filter(
+			value => value.updatedAtMs > request.lastRequestTimeMs,
+		);
+		return values.length ? new ExampleSubscribableUpdate(values) : null;
+	}
+//%endif
+}
@@ -0,0 +1,27 @@
+import { BaseCtlPlugin, type Control } from "@clusterio/ctl";
+import { CommandTree, Command } from "@clusterio/lib";
+//%// We do not check for multi context here because it doesn't make sense to have a ctl without messages
+import { PluginExampleEvent, PluginExampleRequest } from "./messages";
+/* eslint-disable no-console */
+
+const pluginCommands = new CommandTree({
+	name: "__plugin_name__", description: "The default description I forgot to change",
+});
+
+pluginCommands.add(new Command({
+	definition: ["my-command <foo>", "My command description that I really should change", (yargs) => {
+		yargs.positional("foo", { describe: "foo is foo!", type: "string" });
+	}],
+	handler: async function(args: { foo: string }, control: Control) {
+		const response = await control.sendTo("controller", new PluginExampleRequest(args.foo, [1, 2, 3]));
+		console.log(response);
+		console.log(args);
+	},
+}));
+
+/* eslint-enable no-console */
+export class CtlPlugin extends BaseCtlPlugin {
+	async addCommands(rootCommand: CommandTree) {
+		rootCommand.add(pluginCommands);
+	}
+}
@@ -0,0 +1,36 @@
+import * as lib from "@clusterio/lib";
+import { BaseHostPlugin } from "@clusterio/host";
+//%if multi_context
+import { PluginExampleEvent, PluginExampleRequest } from "./messages";
+//%endif
+
+export class HostPlugin extends BaseHostPlugin {
+//%if multi_context
+	async init() {
+		this.host.handle(PluginExampleEvent, this.handlePluginExampleEvent.bind(this));
+		this.host.handle(PluginExampleRequest, this.handlePluginExampleRequest.bind(this));
+	}
+//%endif
+
+	async onHostConfigFieldChanged(field: string, curr: unknown, prev: unknown) {
+		this.logger.info(`host::onInstanceConfigFieldChanged ${field}`);
+	}
+
+	async onShutdown() {
+		this.logger.info("host::onShutdown");
+	}
+//%if multi_context
+
+	async handlePluginExampleEvent(event: PluginExampleEvent) {
+		this.logger.info(JSON.stringify(event));
+	}
+
+	async handlePluginExampleRequest(request: PluginExampleRequest) {
+		this.logger.info(JSON.stringify(request));
+		return {
+			myResponseString: request.myString,
+			myResponseNumbers: request.myNumberArray,
+		};
+	}
+//%endif
+}
@@ -0,0 +1,153 @@
+import * as lib from "@clusterio/lib";
+//%if multi_context
+import * as Messages from "./messages";
+
+lib.definePermission({
+	name: "__plugin_name__.example.permission.event",
+	title: "Example permission event",
+	description: "Example Description. Event. Change me in index.ts",
+	grantByDefault: true,
+});
+
+lib.definePermission({
+	name: "__plugin_name__.example.permission.request",
+	title: "Example permission request",
+	description: "Example Description. Request. Change me in index.ts",
+	grantByDefault: true,
+});
+//%endif
+//%if controller & web // Subscribing requires web content and the controller
+
+lib.definePermission({
+	name: "__plugin_name__.example.permission.subscribe",
+	title: "Example permission subscribe",
+	description: "Example Description. Subscribe. Change me in index.ts",
+	grantByDefault: true,
+});
+//%endif
+//%if web
+
+lib.definePermission({
+	name: "__plugin_name__.page.view",
+	title: "Example page view permission",
+	description: "Example Description. View. Change me in index.ts",
+	grantByDefault: true,
+});
+//%endif
+//%if config
+
+declare module "@clusterio/lib" {
+//%endif
+//%if controller & config
+	export interface ControllerConfigFields {
+		"__plugin_name__.myControllerField": string;
+	}
+//%endif
+//%if host & config
+	export interface HostConfigFields {
+		"__plugin_name__.myHostField": string;
+	}
+//%endif
+//%if instance & config
+	export interface InstanceConfigFields {
+		"__plugin_name__.myInstanceField": string;
+	}
+//%endif
+//%if ctl & config
+	export interface ControlConfigFields {
+		"__plugin_name__.myControlField": string;
+	}
+//%endif
+//%if config
+}
+//%endif
+
+export const plugin: lib.PluginDeclaration = {
+	name: "__plugin_name__",
+	title: "__plugin_name__",
+	description: "Example Description. Plugin. Change me in index.ts",
+//%// There are a lot of statements here to make the formatting look good with and without 'config'
+//%if controller | host & !config | instance & !config | ctl & !config // Blank line for formatting
+
+//%endif
+//%if controller
+	controllerEntrypoint: "./dist/node/controller",
+//%endif
+//%if controller & config
+	controllerConfigFields: {
+		"__plugin_name__.myControllerField": {
+			title: "My Controller Field",
+			description: "This should be removed from index.js",
+			type: "string",
+			initialValue: "Remove Me",
+		},
+	},
+//%endif
+//%if host & config // Blank line for formatting
+
+//%endif
+//%if host
+	hostEntrypoint: "./dist/node/host",
+//%endif
+//%if host & config
+	hostConfigFields: {
+		"__plugin_name__.myHostField": {
+			title: "My Host Field",
+			description: "This should be removed from index.js",
+			type: "string",
+			initialValue: "Remove Me",
+		},
+	},
+//%endif
+//%if instance & config | module & config // Blank line for formatting
+
+//%endif
+//%if instance | module // Modules load an empty instance plugin
+	instanceEntrypoint: "./dist/node/instance",
+//%endif
+//%if instance & config
+	instanceConfigFields: {
+		"__plugin_name__.myInstanceField": {
+			title: "My Instance Field",
+			description: "This should be removed from index.js",
+			type: "string",
+			initialValue: "Remove Me",
+		},
+	},
+//%endif
+//%if ctl & config // Blank line for formatting
+
+//%endif
+//%if ctl
+	ctlEntrypoint: "./dist/node/ctl",
+//%endif
+//%if ctl & config
+	controlConfigFields: {
+		"__plugin_name__.myControlField": {
+			title: "My Control Field",
+			description: "This should be removed from index.js",
+			type: "string",
+			initialValue: "Remove Me",
+		},
+	},
+//%endif
+//%if multi_context // Subscribing requires multi context
+
+	messages: [
+		Messages.PluginExampleEvent,
+		Messages.PluginExampleRequest,
+//%endif
+//%if controller & web // Subscribing requires web content and the controller
+		Messages.ExampleSubscribableUpdate,
+//%endif
+//%if multi_context // Subscribing requires multi context
+	],
+//%endif
+//%if web // Web content template has an example route which is the plugin name
+
+	webEntrypoint: "./web",
+	routes: [
+		"/__plugin_name__",
+	],
+//%endif
+};
@@ -0,0 +1,76 @@
+import * as lib from "@clusterio/lib";
+import { BaseInstancePlugin } from "@clusterio/host";
+//%if multi_context
+import { PluginExampleEvent, PluginExampleRequest } from "./messages";
+//%endif
+//%if module
+
+type PuginExampleIPC = {
+	tick: number,
+	player_name: string,
+};
+//%endif
+
+export class InstancePlugin extends BaseInstancePlugin {
+//%if multi_context | module
+	async init() {
+//%endif
+//%if multi_context
+		this.instance.handle(PluginExampleEvent, this.handlePluginExampleEvent.bind(this));
+		this.instance.handle(PluginExampleRequest, this.handlePluginExampleRequest.bind(this));
+//%endif
+//%if module
+		this.instance.server.handle("__plugin_name__-plugin_example_ipc", this.handlePluginExampleIPC.bind(this));
+//%endif
+//%if multi_context | module
+	}
+//%endif
+
+	async onInstanceConfigFieldChanged(field: string, curr: unknown, prev: unknown) {
+		this.logger.info(`instance::onInstanceConfigFieldChanged ${field}`);
+	}
+
+	async onStart() {
+		// Called once rcon becomes available
+		this.logger.info("instance::onStart");
+	}
+
+	async onStop() {
+		// Called during normal exits before rcon becomes unavailable
+		this.logger.info("instance::onStop");
+	}
+
+	onExit() {
+		// Called during all exits, including crashes and init failures, rcon is not available
+		this.logger.info("instance::onExit");
+	}
+
+	async onPlayerEvent(event: lib.PlayerEvent) {
+		this.logger.info(`onPlayerEvent::onPlayerEvent ${JSON.stringify(event)}`);
+//%if module
+		if (this.instance.status === "running") {
+			await this.sendRcon("/sc __plugin_name__.foo()");
+		}
+//%endif
+	}
+//%if multi_context
+
+	async handlePluginExampleEvent(event: PluginExampleEvent) {
+		this.logger.info(JSON.stringify(event));
+	}
+
+	async handlePluginExampleRequest(request: PluginExampleRequest) {
+		this.logger.info(JSON.stringify(request));
+		return {
+			myResponseString: request.myString,
+			myResponseNumbers: request.myNumberArray,
+		};
+	}
+//%endif
+//%if module
+
+	async handlePluginExampleIPC(event: PuginExampleIPC) {
+		this.logger.info(JSON.stringify(event));
+	}
+//%endif
+}
@@ -0,0 +1,7 @@
+import * as lib from "@clusterio/lib";
+import { BaseInstancePlugin } from "@clusterio/host";
+
+export class InstancePlugin extends BaseInstancePlugin {
+	// This class is empty because an instance plugin must be defined for a module to be injected
+	// This requirement may change in the future to allow for standalone modules
+}
@@ -0,0 +1,97 @@
+import { plainJson, jsonArray, JsonBoolean, JsonNumber, JsonString, StringEnum } from "@clusterio/lib";
+import { Type, Static } from "@sinclair/typebox";
+
+export class PluginExampleEvent {
+	declare ["constructor"]: typeof PluginExampleEvent;
+	static type = "event" as const;
+	static src = ["host", "control"] as const;
+	static dst = ["controller", "host", "instance"] as const;
+	static plugin = "__plugin_name__" as const;
+	static permission = "__plugin_name__.example.permission.event";
+
+	constructor(
+		public myString: string,
+		public myNumberArray: number[],
+	) {
+	}
+
+	static jsonSchema = Type.Object({
+		"myString": Type.String(),
+		"myNumberArray": Type.Array(Type.Number()),
+	});
+
+	static fromJSON(json: Static<typeof PluginExampleEvent.jsonSchema>) {
+		return new PluginExampleEvent(json.myString, json.myNumberArray);
+	}
+}
+
+export class PluginExampleRequest {
+	declare ["constructor"]: typeof PluginExampleRequest;
+	static type = "request" as const;
+	static src = ["host", "control"] as const;
+	static dst = ["controller", "host", "instance"] as const;
+	static plugin = "__plugin_name__" as const;
+	static permission = "__plugin_name__.example.permission.request";
+
+	constructor(
+		public myString: string,
+		public myNumberArray: number[],
+	) {
+	}
+
+	static jsonSchema = Type.Object({
+		"myString": Type.String(),
+		"myNumberArray": Type.Array(Type.Number()),
+	});
+
+	static fromJSON(json: Static<typeof PluginExampleRequest.jsonSchema>) {
+		return new PluginExampleRequest(json.myString, json.myNumberArray);
+	}
+
+	static Response = plainJson(Type.Object({
+		"myResponseString": Type.String(),
+		"myResponseNumbers": Type.Array(Type.Number()),
+	}));
+}
+//%if controller & web // Subscribing requires web content and the controller
+
+export class ExampleSubscribableValue {
+	constructor(
+		public id: string,
+		public updatedAtMs: number,
+		public isDeleted: boolean,
+	) {
+	}
+
+	static jsonSchema = Type.Object({
+		id: Type.String(),
+		updatedAtMs: Type.Number(),
+		isDeleted: Type.Boolean(),
+	});
+
+	static fromJSON(json: Static<typeof this.jsonSchema>) {
+		return new this(json.id, json.updatedAtMs, json.isDeleted);
+	}
+}
+
+export class ExampleSubscribableUpdate {
+	declare ["constructor"]: typeof ExampleSubscribableUpdate;
+	static type = "event" as const;
+	static src = "controller" as const;
+	static dst = "control" as const;
+	static plugin = "__plugin_name__" as const;
+	static permission = "__plugin_name__.example.permission.subscribe";
+
+	constructor(
+		public updates: ExampleSubscribableValue[],
+	) { }
+
+	static jsonSchema = Type.Object({
+		"updates": Type.Array(ExampleSubscribableValue.jsonSchema),
+	});
+
+	static fromJSON(json: Static<typeof this.jsonSchema>) {
+		return new this(json.updates.map(update => ExampleSubscribableValue.fromJSON(update)));
+	}
+}
+//%endif
@@ -0,0 +1,13 @@
+{
+	"compilerOptions": {
+		"composite": true,
+		"declaration": true,
+		"declarationMap": true,
+		"incremental": true,
+		"sourceMap": true,
+		"strict": true,
+		"esModuleInterop": true,
+		"resolveJsonModule": true,
+		"skipLibCheck": true,
+	},
+}
@@ -0,0 +1,13 @@
+{
+	"extends": "./tsconfig.base.json",
+	"compilerOptions": {
+		"lib": ["dom", "es2023"],
+		"module": "es2022",
+		"moduleResolution": "bundler",
+		"target": "es2022",
+		"jsx": "react-jsx",
+		"noEmitOnError": true,
+		"outDir": "${configDir}/dist/browser",
+	},
+	"include": [ "web/**/*.tsx", "web/**/*.ts", "messages.ts", "package.json" ],
+}
@@ -0,0 +1,9 @@
+{
+	"files": [],
+	"references": [
+//%if web
+		{ "path": "./tsconfig.browser.json" },
+//%endif
+		{ "path": "./tsconfig.node.json" }
+	]
+}
@@ -0,0 +1,13 @@
+{
+	"extends": "./tsconfig.base.json",
+	"compilerOptions": {
+		"lib": ["es2023"],
+		"module": "node16",
+		"moduleResolution": "node16",
+		"target": "es2022",
+		"forceConsistentCasingInFileNames": true,
+		"outDir": "${configDir}/dist/node"
+	},
+	"include": ["./**/*.ts"],
+	"exclude": ["test/*", "./dist/*"],
+}
@@ -0,0 +1,93 @@
+import React, {
+	useContext, useEffect, useState,
+//%if controller & web // Subscribing requires web content and the controller
+	useCallback, useSyncExternalStore,
+//%endif
+} from "react";
+
+// import {
+//
+// } from "antd";
+
+import {
+	BaseWebPlugin, PageLayout, PageHeader, Control, ControlContext, notifyErrorHandler,
+} from "@clusterio/web_ui";
+//%if multi_context // Messages requires multi context
+
+import {
+	PluginExampleEvent, PluginExampleRequest,
+//%endif
+//%if controller & web // Subscribing requires web content and the controller
+	ExampleSubscribableUpdate, ExampleSubscribableValue,
+//%endif
+//%if multi_context // Messages requires multi context
+} from "../messages";
+//%endif
+
+import * as lib from "@clusterio/lib";
+
+function MyTemplatePage() {
+	const control = useContext(ControlContext);
+//%if controller // Subscribing requires web content and the controller
+	const plugin = control.plugins.get("__plugin_name__") as WebPlugin;
+	const [subscribableData, synced] = plugin.useSubscribableData();
+//%endif
+
+	return <PageLayout nav={[{ name: "__plugin_name__" }]}>
+		<PageHeader title="__plugin_name__" />
+//%if controller // Subscribing requires web content and the controller
+		Synced: {String(synced)} Data: {JSON.stringify([...subscribableData.values()])}
+//%endif
+	</PageLayout>;
+}
+
+export class WebPlugin extends BaseWebPlugin {
+//%if controller // Subscribing requires web content and the controller
+	subscribableData = new lib.EventSubscriber(ExampleSubscribableUpdate, this.control);
+
+//%endif
+	async init() {
+		this.pages = [
+			{
+				path: "/__plugin_name__",
+				sidebarName: "__plugin_name__",
+				// This permission is client side only, so it must match the permission string of a resource request to be secure
+				// An undefined value means that the page will always be visible
+//%if controller // Subscribing requires web content and the controller
+				permission: "__plugin_name__.example.permission.subscribe",
+//%endif
+//%if !controller
+				permission: "__plugin_name__.example.permission.view",
+//%endif
+				content: <MyTemplatePage/>,
+			},
+		];
+//%if multi_context
+
+		this.control.handle(PluginExampleEvent, this.handlePluginExampleEvent.bind(this));
+		this.control.handle(PluginExampleRequest, this.handlePluginExampleRequest.bind(this));
+//%endif
+	}
+//%if controller // Subscribing requires web content and the controller
+
+	useSubscribableData() {
+		const control = useContext(ControlContext);
+		const subscribe = useCallback((callback: () => void) => this.subscribableData.subscribe(callback), [control]);
+		return useSyncExternalStore(subscribe, () => this.subscribableData.getSnapshot());
+	}
+//%endif
+//%if multi_context
+
+	async handlePluginExampleEvent(event: PluginExampleEvent) {
+		this.logger.info(JSON.stringify(event));
+	}
+
+	async handlePluginExampleRequest(request: PluginExampleRequest) {
+		this.logger.info(JSON.stringify(request));
+		return {
+			myResponseString: request.myString,
+			myResponseNumbers: request.myNumberArray,
+		};
+	}
+//%endif
+}
@@ -0,0 +1,114 @@
+# Templates
+
+Create has the ability to create new plugins from templates to avoid needing to manually copy lots of boiler plate. This folder contains all those templates for both Javascript and Typescript plugins. These templates have custom preprocessor instructions that can be used to alter a template based on developer input, this syntax is described below.
+
+- [The Basics](#the-basics)
+- [Insert Instruction](#insert-instruction) (`__variable__`)
+- [Conditional Instruction](#conditional-instruction) (`//%if` `//%endif`)
+- [Available Variables](#available-variables)
+
+## The Basics
+
+All files can contain preprocessor instructions whether json, js, lua, or anything else. All instructions use the same syntax although it has been designed to work well with js and ts files.
+
+Except for the insert instruction, all preprocessors use a `//%` prefix and must be on their own line. These lines are never included in the output. Parsing is stopped when `//` is encountered to allow for comments on preprocessors. Eg. `//%if foo // this is a comment`.
+
+Empty instructions, aka just comments, can be inserted into templates using `//%//` and are not included in the output file.
+
+`templates/plugin-js` contains all the files which will be used by a javascript only plugin.
+`templates/plugin-ts` contains all the files which will be used by a plugin that supports typescript.
+`templates/common` contains files used by both types of plugins, this is mostly lua code or root files like `package.json`
+
+Files are not copied via wildcards and instead are explicitly listed within `template.js` so any new templates will need to be added there.
+
+## Insert Instruction
+
+There are a number of template variables available to be inserted into templates. All variables are raw string values, that is they are inserted directly into the output file without any modifications. To signify a place to insert a variable you need only surround its identifier with double underscores, examples below.
+
+Example Variables:
+
+```sh
+my_number=1
+my_string=foo
+my_property=bar: "baz"
+```
+
+Example Template:
+
+```ts
+const __my_string__: number = __my_number__;
+console.log(__my_string__);
+
+console.log({
+    foo: "Hello, __my_string__!",
+    __my_property__,
+    my_property: __my_string__,
+});
+```
+
+Example Output:
+
+```ts
+const foo: number = 1;
+console.log(foo);
+
+console.log({
+    foo: "Hello, foo!",
+    bar: "baz",
+    my_property: foo,
+});
+```
+
+## Conditional Instruction
+
+Conditionals allow for code to be included/omitted based on the value of template variables. Currently only boolean logic in [disjunctive normal form](https://en.wikipedia.org/wiki/Disjunctive_normal_form) is supported and any variables that are not booleans are evaluated with the [Boolean constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean).
+
+Variables used in condition statements do not require double underscores. Their values can be inverted using `!`. Arithmetic and comparison operations are not supported. Parentheses are also not supported, conditions must be in DNF.
+
+Conversion to DNF:
+`A & (B | !C)` -> `A & B | A & !C` evaluated as `(A and B) or (A and not C)`
+
+Example Variables:
+
+```sh
+my_string=foo
+say_hello=true
+say_done=true
+verbose=false
+```
+
+Example Template:
+
+```ts
+//%if verbose
+console.log("Starting...");
+//%endif
+//%if say_hello & my_string
+console.log("Hello, __my_string__!");
+//%endif
+//%if say_done | verbose
+console.log("Done.");
+//%endif
+```
+
+Example Output:
+
+```ts
+console.log("Hello, foo!");
+console.log("Done.");
+```
+
+## Available Variables
+
+| Identifier | Example | Description |
+| - | - | - |
+| typescript | `true` / `false` | `true` if typescript templates are included |
+| controller | `true` / `false` | `true` if controller templates are included |
+| host | `true` / `false` | `true` if host templates are included |
+| instance | `true` / `false` | `true` if instance templates are included |
+| module | `true` / `false` | `true` if module templates are included |
+| ctl | `true` / `false` | `true` if control templates are included |
+| web | `true` / `false` | `true` if web templates are included |
+| plugin_name | `my_plugin` | name of the plugin |
+| prepare | `tsc --build` | commands to run for the prepare script |
+| ext | `ts` / `js` | file extension of source files |
@@ -5,7 +5,7 @@
 * @module ctl/ctl
 */
 import fs from "fs-extra";
-import yargs from "yargs";
+import yargs, { type Argv } from "yargs";
 import path from "path";
 import { version } from "./package.json";
 import setBlocking from "set-blocking";
@@ -27,8 +27,8 @@ import BaseCtlPlugin from "./src/BaseCtlPlugin";
 class ControlConnector extends lib.WebSocketClientConnector {
 	private _token: string;

-	constructor(url: string, maxReconnectDelay: number, tlsCa: string | undefined, token: string) {
-		super(url, maxReconnectDelay, tlsCa);
+	constructor(url: string, maxReconnectDelay: number, token: string) {
+		super(url, maxReconnectDelay);
 		this._token = token;
 	}

@@ -54,8 +54,6 @@ class ControlConnector extends lib.WebSocketClientConnector {
 export class Control extends lib.Link {
 	/** Control config used for connecting to the controller. */
 	config: lib.ControlConfig;
-	/** Certificate authority used to validate TLS connections to the controller. */
-	tlsCa?: string;
 	/** Mapping of plugin names to their instance for loaded plugins. */
 	plugins: Map<string, BaseCtlPlugin>;
 	/** Keep the control connection alive after the command completes. */
@@ -64,12 +62,10 @@ export class Control extends lib.Link {
 	constructor(
 		connector: ControlConnector,
 		controlConfig: lib.ControlConfig,
-		tlsCa: string | undefined,
 		ctlPlugins: Map<string, BaseCtlPlugin>
 	) {
 		super(connector);
 		this.config = controlConfig;
-		this.tlsCa = tlsCa;
 		this.plugins = ctlPlugins;

 		this.handle(lib.LogMessageEvent, this.handleLogMessageEvent.bind(this));
@@ -143,8 +139,30 @@ interface CtlArguments {
 	pluginList: string,
 }

-async function startControl() {
-	yargs
+interface InitializeParameters {
+	args: CtlArguments;
+	shouldRun: boolean;
+	ctlPlugins?: Map<string, BaseCtlPlugin>;
+	rootCommands?: lib.CommandTree;
+	controlConfig?: lib.ControlConfig;
+}
+
+export async function initialize(
+	argv: string | string[],
+	ctlPlugins?: Map<string, BaseCtlPlugin>,
+	noLoggerTransport?: boolean,
+): Promise<InitializeParameters> {
+	// Build a fresh, isolated yargs parser each time this function is called.
+	// If the currently loaded yargs object supports .reset() we use that (older versions),
+	// otherwise we fall back to creating a brand-new parser instance by invoking the
+	// yargs factory function directly with an empty argv array.  This avoids Mocha’s
+	// own CLI flags (or anything else that touched yargs earlier in the same process)
+	// from leaking into subsequent parses inside the test runner.
+	const parser: Argv = typeof (yargs as any).reset === "function"
+		? (yargs as any).reset()
+		: (yargs as any)([]);
+
+	parser
 		.scriptName("clusterioctl")
 		.usage("$0 <command> [options]")
 		.option("log-level", {
@@ -167,110 +185,123 @@ async function startControl() {
 			default: "plugin-list.json",
 			type: "string",
 		})
+		.option("bypass-lock-file", { hidden: true, type: "boolean", nargs: 0, default: false })
 		.command("plugin", "Manage available plugins", lib.pluginCommand)
 		.command("control-config", "Manage Control config", lib.configCommand)
-		.wrap(yargs.terminalWidth())
+		.wrap(parser.terminalWidth())
 		.help(false) // Disable help to avoid triggering it on the first parse.
 	;

 	// Parse the args first to get the configured plugin list.
 	// eslint-disable-next-line node/no-sync
-	let args = yargs.parseSync() as CtlArguments;
+	let args = parser.parseSync(argv) as CtlArguments;

-	// Log stream for the ctl session.
-	logger.add(
-		new ConsoleTransport({
-			errorLevels: Object.keys(levels),
-			level: args.logLevel,
-			format: new lib.TerminalFormat(),
-		})
-	);
-	lib.handleUnhandledErrors();
+	// Log stream for the ctl session. Skipped in testing.
+	if (!noLoggerTransport) {
+		logger.add(
+			new ConsoleTransport({
+				errorLevels: Object.keys(levels),
+				level: args.logLevel,
+				format: new lib.TerminalFormat(),
+			})
+		);
+		lib.handleUnhandledErrors();
+	}

-	logger.verbose(`Loading available plugins from ${args.pluginList}`);
-	let pluginList = new Map();
-	try {
-		pluginList = new Map(JSON.parse(await fs.readFile(args.pluginList, "utf8")));
-	} catch (err: any) {
-		if (err.code !== "ENOENT") {
-			throw err;
+	// Discover and load plugins. This check exists to allow tests to inject plugins.
+	if (!ctlPlugins || args._[0] === "plugin") {
+		logger.verbose(`Loading available plugins from ${args.pluginList}`);
+		const pluginList = await lib.loadPluginList(args.pluginList);
+
+		// If the command is plugin management we don't try to load plugins
+		if (args._[0] === "plugin") {
+			await lib.handlePluginCommand(args, pluginList, args.pluginList);
+			return { args, shouldRun: false };
 		}
+
+		logger.verbose("Loading Plugins");
+		ctlPlugins = await loadPlugins(pluginList);
 	}

-	// If the command is plugin management we don't try to load plugins
-	if (args._[0] === "plugin") {
-		await lib.handlePluginCommand(args, pluginList, args.pluginList);
-		return;
-	}
-
-	logger.verbose("Loading Plugins");
-	let ctlPlugins = await loadPlugins(pluginList);
-
-	// Add all cluster management commands including ones from plugins
-	let rootCommands = await commands.registerCommands(ctlPlugins, yargs);
-
-	// Reparse after commands have been added with help and strict checking.
-	args = yargs
+	// Add all commands including from plugins and reparse with help and strict checking.
+	const rootCommands = await commands.registerCommands(ctlPlugins, parser);
+	args = parser
 		.help()
 		.strict()
-		.parse() as CtlArguments
+		.parse(argv) as CtlArguments
 	;

-	logger.verbose(`Loading config from ${args.config}`);
+	const controlConfigPath = args.config;
+	const controlConfigLockPath = `${controlConfigPath}.lock`;
+	if (args.bypassLockFile) {
+		await fs.unlink(controlConfigLockPath).catch(() => {}); // ignore error, file might not exist
+	}
+
 	let controlConfig;
+	const controlConfigLock = new lib.LockFile(controlConfigLockPath);
+	logger.verbose(`Loading config from ${controlConfigPath}`);
 	try {
-		const jsonConfig = JSON.parse(await fs.readFile(args.config, "utf8"));
-		controlConfig = lib.ControlConfig.fromJSON(jsonConfig, "control");
+		controlConfig = await lib.ControlConfig.fromFile("control", controlConfigPath);

 	} catch (err: any) {
 		if (err.code === "ENOENT") {
 			logger.verbose("Config not found, initializing new config");
-			controlConfig = new lib.ControlConfig("control");
+			controlConfig = new lib.ControlConfig("control", undefined, controlConfigPath);

 		} else {
-			throw new lib.StartupError(`Failed to load ${args.config}: ${err.message}`);
+			throw new lib.StartupError(`Failed to load ${args.config}: ${err.stack ?? err.message ?? err}`);
 		}
 	}

 	if (args._.length === 0) {
-		yargs.showHelp();
-		yargs.exit(1, undefined as unknown as Error); // Type definition file is wrong.
+		parser.showHelp();
+		parser.exit(1, undefined as unknown as Error); // Type definition file is wrong.
 	}

 	// Handle the control-config command before trying to connect.
 	if (args._[0] === "control-config") {
-		await lib.handleConfigCommand(args, controlConfig, args.config);
-		return;
+		await lib.handleConfigCommand(args, controlConfig, controlConfigLock);
+		return { args, controlConfig, ctlPlugins, rootCommands, shouldRun: false };
 	}

-	// Determine which command is being executed.
+	return { args, controlConfig, ctlPlugins, rootCommands, shouldRun: true };
+}
+
+export function selectTargetCommand(args: CtlArguments, rootCommands: lib.CommandTree): lib.Command {
 	let commandPath = [...args._] as string[];
 	let targetCommand: lib.CommandTree | lib.Command = rootCommands;
 	while (commandPath.length && targetCommand instanceof lib.CommandTree) {
 		targetCommand = targetCommand.get(commandPath.shift()!)!;
 	}
 	assert(targetCommand instanceof lib.Command);
+	return targetCommand;
+}
+
+async function startControl() {
+	const {
+		args,
+		shouldRun,
+		ctlPlugins,
+		rootCommands,
+		controlConfig,
+	} = await initialize(process.argv.slice(2));
+	if (!shouldRun || !ctlPlugins || !rootCommands || !controlConfig) {
+		return;
+	}

-	// The remaining commands require connecting to the controller.
 	if (!controlConfig.get("control.controller_url") || !controlConfig.get("control.controller_token")) {
 		logger.error("Missing URL and/or token to connect with.  See README.md for setting up access.");
 		process.exitCode = 1;
 		return;
 	}

-	let tlsCa: string | undefined;
-	let tlsCaPath = controlConfig.get("control.tls_ca");
-	if (tlsCaPath) {
-		tlsCa = await fs.readFile(tlsCaPath, "utf8");
-	}
-
 	let controlConnector = new ControlConnector(
 		controlConfig.get("control.controller_url")!,
 		controlConfig.get("control.max_reconnect_delay"),
-		tlsCa,
 		controlConfig.get("control.controller_token")!,
 	);
-	let control = new Control(controlConnector, controlConfig, tlsCa, ctlPlugins);
+
+	let control = new Control(controlConnector, controlConfig, ctlPlugins);
 	try {
 		await controlConnector.connect();
 	} catch (err) {
@@ -285,12 +316,13 @@ async function startControl() {
 		control.shutdown().catch(err => {
 			setBlocking(true);
 			logger.error(err.stack);
-			// eslint-disable-next-line node/no-process-exit
+
 			process.exit(1);
 		});
 	});

 	try {
+		const targetCommand = selectTargetCommand(args, rootCommands);
 		await targetCommand.run(args, control);

 	} catch (err) {
@@ -3,7 +3,7 @@
 	"description": "Clusterio command line management tool",
 	"author": "Hornwitser",
 	"license": "MIT",
-	"version": "2.0.0-alpha.17",
+	"version": "2.0.0-alpha.23",
 	"main": "dist/node/index.js",
 	"scripts": {
 		"prepare": "tsc --build",
@@ -13,28 +13,28 @@
 		"clusterioctl": "./dist/node/ctl.js"
 	},
 	"keywords": [
+		"clusterio",
 		"factorio"
 	],
 	"engines": {
-		"node": ">=18"
+		"node": ">=20"
 	},
 	"dependencies": {
-		"@clusterio/lib": "^2.0.0-alpha.17",
+		"@clusterio/lib": "workspace:*",
+		"set-blocking": "catalog:",
+		"fs-extra": "catalog:",
+		"winston": "catalog:",
 		"as-table": "^1.0.55",
-		"fs-extra": "^11.1.1",
-		"phin": "^3.7.0",
-		"set-blocking": "^2.0.0",
-		"winston": "^3.10.0",
 		"yargs": "^17.7.2"
 	},
 	"publishConfig": {
 		"access": "public"
 	},
 	"devDependencies": {
-		"@types/fs-extra": "^11.0.1",
-		"@types/node": "^20.4.5",
-		"@types/set-blocking": "^2.0.0",
-		"@types/yargs": "^17.0.24",
-		"typescript": "^5.1.6"
+		"@types/fs-extra": "catalog:",
+		"@types/node": "catalog:",
+		"@types/set-blocking": "catalog:",
+		"@types/yargs": "^17.0.33",
+		"typescript": "catalog:"
 	}
 }
@@ -0,0 +1,4 @@
+export function print(...content: any) {
+	// eslint-disable-next-line no-console
+	console.log(...content);
+}
@@ -0,0 +1,201 @@
+import fs from "fs-extra";
+import asTableModule from "as-table";
+import events from "events";
+import os from "os";
+import child_process from "child_process";
+
+import * as lib from "@clusterio/lib";
+import type { Control } from "../ctl";
+import { print } from "./command_ops";
+import { serializedConfigToString, getEditor, configToKeyVal } from "./config_ops";
+
+const asTable = asTableModule.configure({ delimiter: " | " });
+
+export const controllerCommands = new lib.CommandTree({ name: "controller", description: "Controller management" });
+controllerCommands.add(new lib.Command({
+	definition: ["stop", "Stop controller"],
+	handler: async function(_args: object, control: Control) {
+		await control.send(new lib.ControllerStopRequest());
+	},
+}));
+
+controllerCommands.add(new lib.Command({
+	definition: ["restart", "Restart controller"],
+	handler: async function(_args: object, control: Control) {
+		await control.send(new lib.ControllerRestartRequest());
+	},
+}));
+controllerCommands.add(new lib.Command({
+	definition: ["update", "Update the controller", (yargs) => {
+		yargs.option("restart", { alias: "r", type: "boolean", description: "Restart after update" });
+	}],
+	handler: async function(args: { restart: boolean }, control: Control) {
+		await control.send(new lib.ControllerUpdateRequest());
+		if (args.restart) {
+			await control.send(new lib.ControllerRestartRequest());
+		} else {
+			print("Controller updated; a restart is required to apply the changes.");
+		}
+	},
+}));
+
+const controllerConfigCommands = new lib.CommandTree({
+	name: "config", alias: ["c"], description: "controller config management",
+});
+
+controllerConfigCommands.add(new lib.Command({
+	definition: ["list", "List controller configuration"],
+	handler: async function(args: object, control: Control) {
+		let config = await control.send(new lib.ControllerConfigGetRequest());
+
+		for (let [name, value] of Object.entries(config)) {
+			print(`${name} ${JSON.stringify(value)}`);
+		}
+	},
+}));
+
+controllerConfigCommands.add(new lib.Command({
+	definition: ["set <field> [value]", "Set field in controller config", (yargs) => {
+		yargs.positional("field", { describe: "Field to set", type: "string" });
+		yargs.positional("value", { describe: "Value to set", type: "string" });
+		yargs.options({
+			"stdin": { describe: "read value from stdin", nargs: 0, type: "boolean" },
+		});
+	}],
+	handler: async function(args: { field: string, value?: string, stdin?: boolean }, control: Control) {
+		if (args.stdin) {
+			args.value = (await lib.readStream(process.stdin)).toString().replace(/\r?\n$/, "");
+		} else if (args.value === undefined) {
+			args.value = "";
+		}
+		await control.send(new lib.ControllerConfigSetFieldRequest(args.field, args.value));
+	},
+}));
+
+controllerConfigCommands.add(new lib.Command({
+	definition: ["set-prop <field> <prop> [value]", "Set property of field in controller config", (yargs) => {
+		yargs.positional("field", { describe: "Field to set", type: "string" });
+		yargs.positional("prop", { describe: "Property to set", type: "string" });
+		yargs.positional("value", { describe: "JSON parsed value to set", type: "string" });
+		yargs.options({
+			"stdin": { describe: "read value from stdin", nargs: 0, type: "boolean" },
+		});
+	}],
+	handler: async function(args: { field: string, prop: string, value?: string, stdin?: boolean }, control: Control) {
+		if (args.stdin) {
+			args.value = (await lib.readStream(process.stdin)).toString().replace(/\r?\n$/, "");
+		}
+		let value;
+		try {
+			if (args.value !== undefined) {
+				value = JSON.parse(args.value);
+			}
+		} catch (err: any) {
+			// See note for the instance version of set-prop
+			if (args.stdin || /^(\[.*]|{.*}|".*")$/.test(args.value!)) {
+				throw new lib.CommandError(`In parsing value '${args.value}': ${err.message}`);
+			}
+			value = args.value;
+		}
+		await control.send(new lib.ControllerConfigSetPropRequest(args.field, args.prop, value));
+	},
+}));
+controllerConfigCommands.add(new lib.Command({
+	definition: ["edit [editor]", "Edit controller configuration", (yargs) => {
+		yargs.positional("editor", {
+			describe: "Editor to use",
+			type: "string",
+			default: "",
+		});
+	}],
+	handler: async function(args: { editor: string }, control: Control) {
+		let config = await control.send(new lib.ControllerConfigGetRequest());
+		let tmpFile = await lib.getTempFile("ctl-", "-tmp", os.tmpdir());
+		let editor = await getEditor(args.editor);
+		if (editor === undefined) {
+			throw new lib.CommandError(`No editor avalible. Checked CLI input, EDITOR and VISUAL env vars
+							  Try "ctl controller config edit <editor of choice>"`);
+		}
+		let allConfigElements = serializedConfigToString(
+			config, lib.ControllerConfig, {}
+		);
+		await fs.writeFile(tmpFile, allConfigElements);
+		let editorSpawn = child_process.spawn(editor, [tmpFile], {
+			stdio: "inherit",
+			detached: false,
+		});
+		editorSpawn.on("data", (data) => {
+			process.stdout.pipe(data);
+		});
+		await events.once(editorSpawn, "exit");
+		const data = await fs.readFile(tmpFile, "utf8");
+		const final = await configToKeyVal(data);
+		for (let index in final) {
+			if (index in final) {
+				try {
+					await control.send(new lib.ControllerConfigSetFieldRequest(
+						index,
+						final[index],
+					));
+				} catch (err) {
+					// eslint-disable-next-line
+					print(`Attempt to set ${index} to ${final[index] || String(null)} failed; set back to previous value.`);
+					print(err);
+					// If the string is empty, it's better to just print "" instead of nothing
+				}
+			}
+		}
+		try {
+			await fs.unlink(tmpFile);
+		} catch (err) {
+			print("err: temporary file", tmpFile, "could not be deleted.");
+			print("This is not fatal, but they may build up over time if the issue persists.");
+		}
+	},
+}));
+
+controllerCommands.add(controllerConfigCommands);
+
+
+const controllerPluginCommands = new lib.CommandTree({
+	name: "plugin", alias: ["p"], description: "controller plugin inspection",
+});
+controllerPluginCommands.add(new lib.Command({
+	definition: ["list", "List plugins on controller"],
+	handler: async function(args: object, control: Control) {
+		let url = new URL(control.config.get("control.controller_url")!);
+		url.pathname += "api/plugins";
+		let response = await fetch(url);
+		print(asTable(await response.json() as []));
+	},
+}));
+controllerPluginCommands.add(new lib.Command({
+	definition: ["update <plugin>", "Update a plugin on the controller", (yargs) => {
+		yargs.positional("plugin", { describe: "Plugin to update", type: "string" });
+		yargs.option("restart", { alias: "r", type: "boolean", description: "Restart after update" });
+	}],
+	handler: async function(args: { plugin: string, restart: boolean }, control: Control) {
+		await control.sendTo("controller", new lib.PluginUpdateRequest(args.plugin));
+		if (args.restart) {
+			await control.send(new lib.ControllerRestartRequest());
+		} else {
+			print("Plugin updated; a restart is required to apply the changes.");
+		}
+	},
+}));
+controllerPluginCommands.add(new lib.Command({
+	definition: ["install <plugin>", "Install a plugin on the controller", (yargs) => {
+		yargs.positional("plugin", { describe: "Plugin to install", type: "string" });
+		yargs.option("restart", { alias: "r", type: "boolean", description: "Restart after update" });
+	}],
+	handler: async function(args: { plugin: string, restart: boolean }, control: Control) {
+		await control.sendTo("controller", new lib.PluginInstallRequest(args.plugin));
+		if (args.restart) {
+			await control.send(new lib.ControllerRestartRequest());
+		} else {
+			print("Plugin installed; a restart is required to apply the changes.");
+		}
+	},
+}));
+
+controllerCommands.add(controllerPluginCommands);
@@ -0,0 +1,11 @@
+import * as lib from "@clusterio/lib";
+import type { Control } from "../ctl";
+
+export const debugCommands = new lib.CommandTree({ name: "debug", description: "Debugging utilities" });
+debugCommands.add(new lib.Command({
+	definition: ["dump-ws", "Dump WebSocket messages sent and received by controller"],
+	handler: async function(args: object, control: Control) {
+		await control.send(new lib.DebugDumpWsRequest());
+		control.keepOpen = true;
+	},
+}));
@@ -0,0 +1,305 @@
+import fs from "fs-extra";
+import asTableModule from "as-table";
+import events from "events";
+import os from "os";
+import child_process from "child_process";
+
+import * as lib from "@clusterio/lib";
+import { logger } from "@clusterio/lib";
+import type { Control } from "../ctl";
+import { print } from "./command_ops";
+import { serializedConfigToString, getEditor, configToKeyVal } from "./config_ops";
+
+const asTable = asTableModule.configure({ delimiter: " | " });
+
+export const hostCommands = new lib.CommandTree({ name: "host", description: "Host management" });
+hostCommands.add(new lib.Command({
+	definition: ["stop <host>", "Stop the given host", (yargs) => {
+		yargs.positional("host", { describe: "Host to stop", type: "string" });
+	}],
+	handler: async function(args: { host: string }, control: Control) {
+		let hostId = await lib.resolveHost(control, args.host);
+		await control.sendTo({ hostId }, new lib.HostStopRequest());
+	},
+}));
+
+hostCommands.add(new lib.Command({
+	definition: ["restart <host>", "Restart the given host", (yargs) => {
+		yargs.positional("host", { describe: "Host to restart", type: "string" });
+	}],
+	handler: async function(args: { host: string }, control: Control) {
+		let hostId = await lib.resolveHost(control, args.host);
+		await control.sendTo({ hostId }, new lib.HostRestartRequest());
+	},
+}));
+
+hostCommands.add(new lib.Command({
+	definition: [["list", "l"], "List hosts connected to the controller"],
+	handler: async function(args: object, control: Control) {
+		let hosts = await control.send(new lib.HostListRequest());
+		print(asTable(hosts));
+	},
+}));
+
+hostCommands.add(new lib.Command({
+	definition: ["generate-token", "Generate token for a host", (yargs) => {
+		yargs.option("id", { type: "number", nargs: 1, describe: "Host id" });
+	}],
+	handler: async function(args: { id?: number }, control: Control) {
+		let hostId = typeof args.id === "number" ? args.id : undefined;
+		let response = await control.send(new lib.HostGenerateTokenRequest(hostId));
+		print(response);
+	},
+}));
+
+hostCommands.add(new lib.Command({
+	definition: ["revoke-token <host>", "Revoke all tokens for a host", (yargs) => {
+		yargs.positional("host", { describe: "Host to revoke tokens for", type: "string" });
+	}],
+	handler: async function(args: { host: string }, control: Control) {
+		let hostId = await lib.resolveHost(control, args.host);
+		await control.send(new lib.HostRevokeTokensRequest(hostId));
+	},
+}));
+
+hostCommands.add(new lib.Command({
+	definition: ["create-config", "Create host config", (yargs) => {
+		yargs.option("id", { type: "number", nargs: 1, describe: "Host id" });
+		yargs.option("name", { type: "string", nargs: 1, describe: "Host name" });
+		yargs.option("generate-token", {
+			type: "boolean", nargs: 0, describe: "Generate authentication token", default: false,
+		});
+		yargs.option("output", {
+			type: "string", nargs: 1, describe: "Path to output config (- for stdout)", default: "config-host.json",
+		});
+	}],
+	handler: async function(
+		args: { id?: number, name?: string, generateToken: boolean, output: string },
+		control: Control
+	) {
+		let config = await control.send(
+			new lib.HostConfigCreateRequest(args.id, args.name, args.generateToken)
+		);
+
+		let content = JSON.stringify(config, null, "\t");
+		if (args.output === "-") {
+			print(content);
+		} else {
+			logger.info(`Writing ${args.output}`);
+			try {
+				await fs.outputFile(args.output, content, { flag: "wx" });
+			} catch (err: any) {
+				if (err.code === "EEXIST") {
+					throw new lib.CommandError(`File ${args.output} already exists`);
+				}
+				throw err;
+			}
+		}
+	},
+}));
+hostCommands.add(new lib.Command({
+	definition: ["update <host>", "Update the host", (yargs) => {
+		yargs.positional("host", { describe: "Host to update", type: "string" });
+		yargs.option("restart", { alias: "r", type: "boolean", description: "Restart after update" });
+	}],
+	handler: async function(args: { host: string, restart: boolean }, control: Control) {
+		let hostId = await lib.resolveHost(control, args.host);
+		await control.sendTo({ hostId }, new lib.HostUpdateRequest());
+		if (args.restart) {
+			await control.sendTo({ hostId }, new lib.HostRestartRequest());
+		} else {
+			print("Host updated; a restart is required to apply the changes.");
+		}
+	},
+}));
+
+
+const hostConfigCommands = new lib.CommandTree({
+	name: "config", alias: ["c"], description: "Host config management",
+});
+hostConfigCommands.add(new lib.Command({
+	definition: ["list <host>", "List configuration for a host", (yargs) => {
+		yargs.positional("host", { describe: "Host to list config for", type: "string" });
+	}],
+	handler: async function(args: { host: string }, control: Control) {
+		let hostId = await lib.resolveHost(control, args.host);
+		let config = await control.sendTo({ hostId }, new lib.HostConfigGetRequest());
+
+		for (let [name, value] of Object.entries(config)) {
+			print(`${name} ${JSON.stringify(value)}`);
+		}
+	},
+}));
+
+hostConfigCommands.add(new lib.Command({
+	definition: ["set <host> <field> [value]", "Set field in host config", (yargs) => {
+		yargs.positional("host", { describe: "Host to set config on", type: "string" });
+		yargs.positional("field", { describe: "Field to set", type: "string" });
+		yargs.positional("value", { describe: "Value to set", type: "string" });
+		yargs.options({
+			"stdin": { describe: "read value from stdin", nargs: 0, type: "boolean" },
+		});
+	}],
+	handler: async function(
+		args: { host: string, field: string, value?: string, stdin?: boolean },
+		control: Control,
+	) {
+		let hostId = await lib.resolveHost(control, args.host);
+		if (args.stdin) {
+			args.value = (await lib.readStream(process.stdin)).toString().replace(/\r?\n$/, "");
+		} else if (args.value === undefined) {
+			args.value = "";
+		}
+		await control.sendTo({ hostId }, new lib.HostConfigSetFieldRequest(args.field, args.value));
+	},
+}));
+
+hostConfigCommands.add(new lib.Command({
+	definition: ["set-prop <host> <field> <prop> [value]", "Set property of field in host config", (yargs) => {
+		yargs.positional("host", { describe: "Host to set config on", type: "string" });
+		yargs.positional("field", { describe: "Field to set", type: "string" });
+		yargs.positional("prop", { describe: "Property to set", type: "string" });
+		yargs.positional("value", { describe: "JSON parsed value to set", type: "string" });
+		yargs.options({
+			"stdin": { describe: "read value from stdin", nargs: 0, type: "boolean" },
+		});
+	}],
+	handler: async function(
+		args: { host: string, field: string, prop: string, value?: string, stdin?: boolean },
+		control: Control
+	) {
+		let hostId = await lib.resolveHost(control, args.host);
+		if (args.stdin) {
+			args.value = (await lib.readStream(process.stdin)).toString().replace(/\r?\n$/, "");
+		}
+		let value;
+		try {
+			if (args.value !== undefined) {
+				value = JSON.parse(args.value);
+			}
+		} catch (err: any) {
+			// See note for the instance version of set-prop
+			if (args.stdin || /^(\[.*]|{.*}|".*")$/.test(args.value!)) {
+				throw new lib.CommandError(`In parsing value '${args.value}': ${err.message}`);
+			}
+			value = args.value;
+		}
+		await control.sendTo({ hostId }, new lib.HostConfigSetPropRequest(args.field, args.prop, value));
+	},
+}));
+
+hostConfigCommands.add(new lib.Command({
+	definition: ["edit <host> [editor]", "Edit host configuration", (yargs) => {
+		yargs.positional("host", { describe: "Host to set config on", type: "string" });
+		yargs.positional("editor", {
+			describe: "Editor to use",
+			type: "string",
+			default: "",
+		});
+	}],
+	handler: async function(args: { host: string, editor: string }, control: Control) {
+		let hostId = await lib.resolveHost(control, args.host);
+		let config = await control.sendTo({ hostId }, new lib.HostConfigGetRequest());
+		let tmpFile = await lib.getTempFile("ctl-", "-tmp", os.tmpdir());
+		let editor = await getEditor(args.editor);
+		if (editor === undefined) {
+			throw new lib.CommandError(`No editor avalible. Checked CLI input, EDITOR and VISUAL env vars
+							  Try "ctl controller config edit <editor of choice>"`);
+		}
+		let disallowedList = {"host.id": 0};
+		let allConfigElements = serializedConfigToString(
+			config,
+			lib.HostConfig,
+			disallowedList
+		);
+		await fs.writeFile(tmpFile, allConfigElements);
+		let editorSpawn = child_process.spawn(editor, [tmpFile], {
+			stdio: "inherit",
+			detached: false,
+		});
+		editorSpawn.on("data", (data) => {
+			process.stdout.pipe(data);
+		});
+		await events.once(editorSpawn, "exit");
+		const data = await fs.readFile(tmpFile, "utf8");
+		const final = await configToKeyVal(data);
+		for (let index in final) {
+			if (index in final) {
+				try {
+					await control.sendTo({ hostId }, new lib.HostConfigSetFieldRequest(
+						index,
+						final[index],
+					));
+				} catch (err) {
+					// eslint-disable-next-line
+					print(`\n\n\nAttempt to set ${index} to ${final[index] || String(null)} failed; set back to previous value.`);
+					// If the string is empty, it's better to just print "" instead of nothing
+					print("This message shouldn't normally appear; if the below message does not indicate it");
+					print("was a user mistake, please report it to the clustorio devs.");
+					// added this because it could be a missed entry in disallowedList
+					// i've added all the vanilla clustorio configs, but there may be
+					// some modded ones that need to be added.
+					print(err);
+				}
+			}
+		}
+		try {
+			await fs.unlink(tmpFile);
+		} catch (err) {
+			print("err: temporary file", tmpFile, "could not be deleted.");
+			print("This is not fatal, but they may build up over time if the issue persists.");
+		}
+	},
+}));
+
+hostCommands.add(hostConfigCommands);
+
+
+const hostPluginCommands = new lib.CommandTree({
+	name: "plugin", alias: ["p"], description: "host plugin inspection",
+});
+hostPluginCommands.add(new lib.Command({
+	definition: ["list <host>", "List plugins on a host", (yargs) => {
+		yargs.positional("host", { describe: "Host to list for", type: "string" });
+	}],
+	handler: async function(args: { host: string }, control: Control) {
+		let hostId = await lib.resolveHost(control, args.host);
+		const plugins = await control.sendTo({ hostId }, new lib.PluginListRequest());
+		print(asTable(plugins.map(p => ({
+			title: p.title, version: p.version, loaded: p.loaded, enabled: p.enabled, npmPackage: p.npmPackage,
+		}))));
+	},
+}));
+hostPluginCommands.add(new lib.Command({
+	definition: ["update <host> <plugin>", "Update a plugin on a host", (yargs) => {
+		yargs.positional("host", { describe: "Host to update on", type: "string" });
+		yargs.positional("plugin", { describe: "Plugin to update", type: "string" });
+		yargs.option("restart", { alias: "r", type: "boolean", description: "Restart after update" });
+	}],
+	handler: async function(args: { host: string, plugin: string, restart: boolean }, control: Control) {
+		let hostId = await lib.resolveHost(control, args.host);
+		await control.sendTo({ hostId }, new lib.PluginUpdateRequest(args.plugin));
+		if (args.restart) {
+			await control.sendTo({ hostId }, new lib.HostRestartRequest());
+		} else {
+			print("Plugin updated; a restart is required to apply the changes.");
+		}
+	},
+}));
+hostPluginCommands.add(new lib.Command({
+	definition: ["install <host> <plugin>", "Install a plugin on a host", (yargs) => {
+		yargs.positional("host", { describe: "Host to install on", type: "string" });
+		yargs.positional("plugin", { describe: "Plugin to install", type: "string" });
+		yargs.option("restart", { alias: "r", type: "boolean", description: "Restart after update" });
+	}],
+	handler: async function(args: { host: string, plugin: string, restart: boolean }, control: Control) {
+		let hostId = await lib.resolveHost(control, args.host);
+		await control.sendTo({ hostId }, new lib.PluginInstallRequest(args.plugin));
+		if (args.restart) {
+			await control.sendTo({ hostId }, new lib.HostRestartRequest());
+		} else {
+			print("Plugin installed; a restart is required to apply the changes.");
+		}
+	},
+}));
+hostCommands.add(hostPluginCommands);
@@ -0,0 +1,685 @@
+import fs from "fs-extra";
+import asTableModule from "as-table";
+import events from "events";
+import path from "path";
+import os from "os";
+import child_process from "child_process";
+import stream from "stream";
+import util from "util";
+
+import * as lib from "@clusterio/lib";
+import { logger } from "@clusterio/lib";
+import type { Control } from "../ctl";
+import { print } from "./command_ops";
+import { serializedConfigToString, getEditor, configToKeyVal } from "./config_ops";
+
+const asTable = asTableModule.configure({ delimiter: " | " });
+const finished = util.promisify(stream.finished);
+
+export const instanceCommands = new lib.CommandTree({
+	name: "instance", alias: ["i"], description: "Instance management",
+});
+instanceCommands.add(new lib.Command({
+	definition: [["list", "l"], "List instances known to the controller"],
+	handler: async function(args: object, control: Control) {
+		let list = await control.send(new lib.InstanceDetailsListRequest());
+		print(asTable(list));
+	},
+}));
+
+instanceCommands.add(new lib.Command({
+	definition: ["create <name>", "Create an instance", (yargs) => {
+		// XXX TODO: set any specific options?
+		yargs.positional("name", { describe: "Instance name", type: "string" });
+		yargs.options({
+			"id": { type: "number", nargs: 1, describe: "Instance id" },
+			"from": { type: "number", nargs: 1, describe: "Clone config from instance id" },
+		});
+	}],
+	handler: async function(args: { name: string, id?: number, from?: number, }, control: Control) {
+		let instanceConfig = new lib.InstanceConfig("control");
+		if (args.id !== undefined) {
+			instanceConfig.set("instance.id", args.id);
+		}
+		instanceConfig.set("instance.name", args.name);
+		await control.send(new lib.InstanceCreateRequest(
+			instanceConfig.toRemote("controller", [
+				"instance.id", "instance.name",
+			]),
+			args.from
+		));
+	},
+}));
+
+const instanceConfigCommands = new lib.CommandTree({
+	name: "config", alias: ["c"], description: "Instance config management",
+});
+instanceConfigCommands.add(new lib.Command({
+	definition: ["list <instance>", "List configuration for an instance", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to list config for", type: "string" });
+	}],
+	handler: async function(args: { instance: string }, control: Control) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		let config = await control.send(new lib.InstanceConfigGetRequest(instanceId));
+
+		for (let [name, value] of Object.entries(config)) {
+			print(`${name} ${JSON.stringify(value)}`);
+		}
+	},
+}));
+
+instanceConfigCommands.add(new lib.Command({
+	definition: ["set <instance> <field> [value]", "Set field in instance config", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to set config on", type: "string" });
+		yargs.positional("field", { describe: "Field to set", type: "string" });
+		yargs.positional("value", { describe: "Value to set", type: "string" });
+		yargs.options({
+			"stdin": { describe: "read value from stdin", nargs: 0, type: "boolean" },
+		});
+	}],
+	handler: async function(
+		args: { instance: string, field: string, value?: string, stdin?: boolean },
+		control: Control,
+	) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		if (args.stdin) {
+			args.value = (await lib.readStream(process.stdin)).toString().replace(/\r?\n$/, "");
+		} else if (args.value === undefined) {
+			args.value = "";
+		}
+		await control.send(new lib.InstanceConfigSetFieldRequest(instanceId, args.field, args.value));
+	},
+}));
+
+instanceConfigCommands.add(new lib.Command({
+	definition: ["set-prop <instance> <field> <prop> [value]", "Set property of field in instance config", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to set config on", type: "string" });
+		yargs.positional("field", { describe: "Field to set", type: "string" });
+		yargs.positional("prop", { describe: "Property to set", type: "string" });
+		yargs.positional("value", { describe: "JSON parsed value to set", type: "string" });
+		yargs.options({
+			"stdin": { describe: "read value from stdin", nargs: 0, type: "boolean" },
+		});
+	}],
+	handler: async function(
+		args: { instance: string, field: string, prop: string, value?: string, stdin?: boolean },
+		control: Control
+	) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		if (args.stdin) {
+			args.value = (await lib.readStream(process.stdin)).toString().replace(/\r?\n$/, "");
+		}
+		let value;
+		try {
+			if (args.value !== undefined) {
+				value = JSON.parse(args.value);
+			}
+		} catch (err: any) {
+			// If this is from stdin or looks like an array, object or string
+			// literal throw the parse error, otherwise assume this is a string.
+			// The resoning behind this is that correctly quoting the string
+			// with the all the layers of quote removal at play is difficult.
+			// See the following table for how to pass "That's a \" quote" in
+			// different environments:
+			// ----------------------- WARNING -------------------------------
+			// This table is most likely invalid due a change in yargs parsing
+			// ---------------------------------------------------------------
+			// cmd              : """""That's a \\"" quote"""""
+			// cmd + npx        : """""""""""That's a \\\\"""" quote"""""""""""
+			// PowerShell       : '"""""That''s a \\"" quote"""""'
+			// PowerShell + npx : '"""""""""""That''s a \\\\"""" quote"""""""""""'
+			// bash             : '""That'\''s a \" quote""'
+			// bash + npx       : '""That'\''s a \" quote""'
+			// bash + npx -s sh : "'\"\"That'\\''s a \\\" quote\"\"'"
+			if (args.stdin || /^(\[.*]|{.*}|".*")$/.test(args.value!)) {
+				throw new lib.CommandError(`In parsing value '${args.value}': ${err.message}`);
+			}
+			value = args.value;
+		}
+		await control.send(new lib.InstanceConfigSetPropRequest(instanceId, args.field, args.prop, value));
+	},
+}));
+
+instanceConfigCommands.add(new lib.Command({
+	definition: ["edit <instance> [editor]", "Edit instance configuration", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to set config on", type: "string" });
+		yargs.positional("editor", {
+			describe: "Editor to use",
+			type: "string",
+			default: "",
+		});
+	}],
+	handler: async function(args: { instance: string, editor: string }, control: Control) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		let config = await control.send(new lib.InstanceConfigGetRequest(instanceId));
+		let tmpFile = await lib.getTempFile("ctl-", "-tmp", os.tmpdir());
+		let editor = await getEditor(args.editor);
+		if (editor === undefined) {
+			throw new lib.CommandError(`No editor avalible. Checked CLI input, EDITOR and VISUAL env vars
+							  Try "ctl controller config edit <editor of choice>"`);
+		}
+		let disallowedList = {"instance.id": 0, "instance.assigned_host": 0, "factorio.settings": 0};
+		let allConfigElements = serializedConfigToString(
+			config,
+			lib.InstanceConfig,
+			disallowedList
+		);
+		await fs.writeFile(tmpFile, allConfigElements);
+		let editorSpawn = child_process.spawn(editor, [tmpFile], {
+			stdio: "inherit",
+			detached: false,
+		});
+		editorSpawn.on("data", (data) => {
+			process.stdout.pipe(data);
+		});
+		await events.once(editorSpawn, "exit");
+		const data = await fs.readFile(tmpFile, "utf8");
+		const final = await configToKeyVal(data);
+		for (let index in final) {
+			if (index in final) {
+				try {
+					await control.send(new lib.InstanceConfigSetFieldRequest(
+						instanceId,
+						index,
+						final[index],
+					));
+				} catch (err) {
+					// eslint-disable-next-line
+					print(`\n\n\nAttempt to set ${index} to ${final[index] || String(null)} failed; set back to previous value.`);
+					// If the string is empty, it's better to just print "" instead of nothing
+					print("This message shouldn't normally appear; if the below message does not indicate it");
+					print("was a user mistake, please report it to the clustorio devs.");
+					// added this because it could be a missed entry in disallowedList
+					// i've added all the vanilla clustorio configs, but there may be
+					// some modded ones that need to be added.
+					print(err);
+				}
+			}
+		}
+		try {
+			await fs.unlink(tmpFile);
+		} catch (err) {
+			print("err: temporary file", tmpFile, "could not be deleted.");
+			print("This is not fatal, but they may build up over time if the issue persists.");
+		}
+	},
+}));
+instanceCommands.add(instanceConfigCommands);
+
+instanceCommands.add(new lib.Command({
+	definition: ["assign <instance> [host]", "Assign instance to a host", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to assign", type: "string" });
+		yargs.positional("host", { describe: "Host to assign to or unassign if none", type: "string" });
+	}],
+	handler: async function(args: { instance: string, host?: string }, control: Control) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		let hostId = args.host ? await lib.resolveHost(control, args.host) : undefined;
+		await control.send(new lib.InstanceAssignRequest(instanceId, hostId));
+	},
+}));
+
+async function loadMapSettings(
+	args: { seed?: number, mapExchangeString?: string, mapGenSettings?: string, mapSettings?: string},
+) {
+	let seed = args.seed;
+	let mapGenSettings;
+	let mapSettings;
+	if (args.mapExchangeString) {
+		let parsed = lib.readMapExchangeString(args.mapExchangeString);
+		mapGenSettings = parsed.map_gen_settings;
+		mapSettings = parsed.map_settings;
+	}
+	if (args.mapGenSettings) {
+		mapGenSettings = JSON.parse((await fs.readFile(args.mapGenSettings)).toString());
+	}
+	if (args.mapSettings) {
+		mapSettings = JSON.parse((await fs.readFile(args.mapSettings)).toString());
+	}
+
+	return {
+		seed,
+		mapGenSettings,
+		mapSettings,
+	};
+}
+
+const instanceSaveCommands = new lib.CommandTree({
+	name: "save", alias: ["s"], description: "Instance save management",
+});
+instanceSaveCommands.add(new lib.Command({
+	definition: ["list <instance>", "list saves on an instance", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to list saves on", type: "string" });
+	}],
+	handler: async function(args: { instance: string }, control: Control) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		let saves = await control.sendTo("controller", new lib.InstanceSaveDetailsListRequest());
+		saves = saves.filter(save => save.instanceId === instanceId);
+		print(asTable(saves.map(
+			({ mtimeMs, ...rest }) => ({ ...rest, mtime: new Date(mtimeMs).toLocaleString() })
+		)));
+	},
+}));
+
+instanceSaveCommands.add(new lib.Command({
+	definition: ["create <instance> [name]", "Create a new save on an instance", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to create on", type: "string" });
+		yargs.positional("name", { describe: "Name of save to create.", type: "string", default: "world.zip" });
+		yargs.options({
+			"seed": { describe: "Seed to use, takes precedence over map-gen-settings", nargs: 1, type: "number" },
+			"map-exchange-string": { describe: "Map exchange string to use for the save", nargs: 1, type: "string" },
+			"map-gen-settings": { describe: "path to file to use for map-gen-settings", nargs: 1, type: "string" },
+			"map-settings": { describe: "path to file to use for map-settings", nargs: 1, type: "string" },
+		});
+	}],
+	handler: async function(
+		args: {
+			instance: string,
+			name: string,
+			seed?: number,
+			mapExchangeString?: string,
+			mapGenSettings?: string,
+			mapSettings?: string,
+		},
+		control: Control
+	) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		let { seed, mapGenSettings, mapSettings } = await loadMapSettings(args);
+		await control.setLogSubscriptions({ instanceIds: [instanceId] });
+		await control.sendTo(
+			{ instanceId },
+			new lib.InstanceCreateSaveRequest(args.name, seed, mapGenSettings, mapSettings),
+		);
+	},
+}));
+
+instanceSaveCommands.add(new lib.Command({
+	definition: ["rename <instance> <old-name> <new-name>", "Rename a save on an instance", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to rename save on", type: "string" });
+		yargs.positional("old-name", { describe: "Old name of save.", type: "string" });
+		yargs.positional("new-name", { describe: "New name of save.", type: "string" });
+	}],
+	handler: async function(args: { instance: string, oldName: string, newName: string }, control: Control) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		await control.send(new lib.InstanceRenameSaveRequest(instanceId, args.oldName, args.newName));
+	},
+}));
+
+instanceSaveCommands.add(new lib.Command({
+	definition: ["copy <instance> <source> <destination>", "Copy a save on an instance", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to copy save on", type: "string" });
+		yargs.positional("source", { describe: "Save to copy.", type: "string" });
+		yargs.positional("destination", { describe: "Name of copy.", type: "string" });
+	}],
+	handler: async function(args: { instance: string, source: string, destination: string }, control: Control) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		await control.send(new lib.InstanceCopySaveRequest(instanceId, args.source, args.destination));
+	},
+}));
+
+instanceSaveCommands.add(new lib.Command({
+	definition: ["upload <instance> <filepath>", "Upload a save to an instance", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to upload to", type: "string" });
+		yargs.positional("filepath", { describe: "Path to save to upload", type: "string" });
+		yargs.options({
+			"name": { describe: "Name to give save on server", nargs: 1, type: "string" },
+		});
+	}],
+	handler: async function(args: { instance: string, filepath: string, name?: string }, control: Control) {
+		let filename = args.name || path.basename(args.filepath);
+		if (!filename.endsWith(".zip")) {
+			throw new lib.CommandError("Save name must end with .zip");
+		}
+
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		let url = new URL(control.config.get("control.controller_url")!);
+		url.pathname += "api/upload-save";
+		url.searchParams.append("instance_id", String(instanceId));
+		url.searchParams.append("filename", filename);
+
+		const response = await fetch(url, {
+			method: "POST",
+			body: await fs.createReadStream(args.filepath),
+			duplex: "half",
+			headers: {
+				"X-Access-Token": control.config.get("control.controller_token")!,
+				"Content-Type": "application/zip",
+			},
+		});
+
+		type ResponseType = { errors?: string[], request_errors?: string[], saves?: string[] };
+		const result = await response.json() as ResponseType;
+
+		for (let error of result.errors || []) {
+			logger.error(error);
+		}
+
+		for (let requestError of result.request_errors || []) {
+			logger.error(requestError);
+		}
+
+		if (result.saves && result.saves.length) {
+			logger.info(`Successfully uploaded as ${result.saves[0]}`);
+		}
+
+		if ((result.errors || []).length || (result.request_errors || []).length) {
+			throw new lib.CommandError("Uploading save failed");
+		}
+	},
+}));
+
+instanceSaveCommands.add(new lib.Command({
+	definition: [
+		"transfer <source-instance> <source-save> <target-instance> [target-save]",
+		"Transfer a save between instances",
+		(yargs) => {
+			yargs.positional("source-instance", { describe: "Instance to transfer save from", type: "string" });
+			yargs.positional("source-save", { describe: "Save to transfer.", type: "string" });
+			yargs.positional("target-instance", { describe: "Instance to transfer to", type: "string" });
+			yargs.positional("target-save", { describe: "Name to give transferred save.", type: "string" });
+			yargs.options({
+				"copy": { describe: "Copy instead of moving the save", type: "boolean", default: false },
+			});
+		},
+	],
+	handler: async function(
+		args: {
+			sourceInstance: string,
+			sourceSave: string,
+			targetInstance: string,
+			targetSave: string,
+			copy: boolean,
+		},
+		control: Control
+	) {
+		let sourceInstanceId = await lib.resolveInstance(control, args.sourceInstance);
+		let targetInstanceId = await lib.resolveInstance(control, args.targetInstance);
+		let storedName = await control.send(
+			new lib.InstanceTransferSaveRequest(
+				sourceInstanceId,
+				args.sourceSave,
+				targetInstanceId,
+				args.targetSave || args.sourceSave,
+				args.copy
+			)
+		);
+		print(`Transferred as ${storedName} to ${args.targetInstance}.`);
+	},
+}));
+
+instanceSaveCommands.add(new lib.Command({
+	definition: ["download <instance> <save>", "Download a save from an instance", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to download save from", type: "string" });
+		yargs.positional("save", { describe: "Save to download", type: "string" });
+	}],
+	handler: async function(args: { instance: string, save: string }, control: Control) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		let streamId = await control.send(new lib.InstanceDownloadSaveRequest(instanceId, args.save));
+
+		let url = new URL(control.config.get("control.controller_url")!);
+		url.pathname += `api/stream/${streamId}`;
+		let response = await fetch(url);
+		if (!response.body) {
+			throw new lib.CommandError("Got empty response from server.");
+		}
+
+		let writeStream;
+		let tempFilename = args.save.replace(/(\.zip)?$/, ".tmp.zip");
+		while (true) {
+			try {
+				writeStream = fs.createWriteStream(tempFilename, { flags: "wx" });
+				await events.once(writeStream, "open");
+				break;
+			} catch (err: any) {
+				if (err.code === "EEXIST") {
+					tempFilename = await lib.findUnusedName(".", tempFilename, ".tmp.zip");
+				} else {
+					throw err;
+				}
+			}
+		}
+		stream.Readable.fromWeb(response.body).pipe(writeStream);
+		await finished(writeStream);
+
+		let filename = await lib.findUnusedName(".", args.save, ".zip");
+		await fs.rename(tempFilename, filename);
+
+		logger.info(`Downloaded ${args.save}${args.save === filename ? "" : ` as ${filename}`}`);
+	},
+}));
+
+instanceSaveCommands.add(new lib.Command({
+	definition: ["delete <instance> <save>", "Delete a save from an instance", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to delete save from", type: "string" });
+		yargs.positional("save", { describe: "Save to delete", type: "string" });
+	}],
+	handler: async function(args: { instance: string, save: string }, control: Control) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		await control.send(new lib.InstanceDeleteSaveRequest(instanceId, args.save));
+	},
+}));
+instanceCommands.add(instanceSaveCommands);
+
+instanceCommands.add(new lib.Command({
+	definition: ["export-data <instance>", "Export item icons and locale from instance", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to export from", type: "string" });
+	}],
+	handler: async function(args: { instance: string }, control: Control) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		await control.setLogSubscriptions({ instanceIds: [instanceId] });
+		await control.sendTo({ instanceId }, new lib.InstanceExportDataRequest());
+	},
+}));
+
+instanceCommands.add(new lib.Command({
+	definition: ["extract-players <instance>", "Extract players from running save into the cluster.", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to extract players and online time from", type: "string" });
+	}],
+	handler: async function(args: { instance: string }, control: Control) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		await control.setLogSubscriptions({ instanceIds: [instanceId] });
+		await control.sendTo({ instanceId }, new lib.InstanceExtractPlayersRequest());
+	},
+}));
+
+instanceCommands.add(new lib.Command({
+	definition: ["start <instance>", "Start instance", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to start", type: "string" });
+		yargs.options({
+			"save": { describe: "Save to load, defaults to latest", nargs: 1, type: "string" },
+			"keep-open": { describe: "Keep console open", nargs: 0, type: "boolean", default: false },
+		});
+	}],
+	handler: async function(args: { instance: string, save?: string, keepOpen: boolean }, control: Control) {
+		const instanceId = await lib.resolveInstance(control, args.instance);
+		await control.setLogSubscriptions({ instanceIds: [instanceId] });
+		await control.sendTo({ instanceId }, new lib.InstanceStartRequest(args.save));
+		control.keepOpen = args.keepOpen;
+	},
+}));
+instanceCommands.add(new lib.Command({
+	definition: ["restart <instance>", "Restart instance", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to restart", type: "string" });
+		yargs.options({
+			"save": { describe: "Save to load, defaults to latest", nargs: 1, type: "string" },
+			"keep-open": { describe: "Keep console open", nargs: 0, type: "boolean", default: false },
+		});
+	}],
+	handler: async function(args: { instance: string, save?: string, keepOpen: boolean }, control: Control) {
+		const instanceId = await lib.resolveInstance(control, args.instance);
+		await control.setLogSubscriptions({ instanceIds: [instanceId] });
+		await control.sendTo({ instanceId }, new lib.InstanceRestartRequest(args.save));
+		control.keepOpen = args.keepOpen;
+	},
+}));
+
+instanceCommands.add(new lib.Command({
+	definition: ["start-all", "Start all stopped instances (respects exclude_from_start_all setting)", (yargs) => {
+		yargs.options({
+			"force": {
+				describe: "Start instances even if they have exclude_from_start_all set",
+				nargs: 0,
+				type: "boolean",
+				default: false,
+			},
+		});
+	}],
+	handler: async function(args: { force: boolean }, control: Control) {
+		// Get all instances
+		const instances = await control.send(new lib.InstanceDetailsListRequest());
+
+		// Filter instances that should be started
+		const instancesToStart = instances.filter((instance: lib.InstanceDetails) => {
+			// Only start instances that are currently stopped
+			if (instance.status !== "stopped") {
+				return false;
+			}
+
+			// Respect exclude_from_start_all setting unless --force is used
+			if (!args.force && instance.excludeFromStartAll) {
+				return false;
+			}
+
+			return true;
+		});
+
+		if (instancesToStart.length === 0) {
+			print("No instances to start.");
+			return;
+		}
+
+		print(`Starting ${instancesToStart.length} instance(s):`);
+		for (const instance of instancesToStart) {
+			print(`  - ${instance.name} (ID: ${instance.id})`);
+		}
+
+		// Start all filtered instances
+		const startPromises = instancesToStart.map(async (instance: lib.InstanceDetails) => {
+			try {
+				await control.sendTo({ instanceId: instance.id }, new lib.InstanceStartRequest());
+				print(`✓ Started ${instance.name}`);
+			} catch (error) {
+				print(`✗ Failed to start ${instance.name}: ${error}`);
+			}
+		});
+
+		await Promise.all(startPromises);
+		print("Start all operation completed.");
+	},
+}));
+
+instanceCommands.add(new lib.Command({
+	definition: ["load-scenario <instance> <scenario>", "Start instance by loading a scenario", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to start", type: "string" });
+		yargs.positional("scenario", { describe: "Scenario to load", type: "string" });
+		yargs.options({
+			"seed": { describe: "Seed to use, takes precedence over map-gen-settings", nargs: 1, type: "number" },
+			"map-exchange-string": { describe: "Map exchange string to use for the save", nargs: 1, type: "string" },
+			"map-gen-settings": { describe: "path to file to use for map-gen-settings", nargs: 1, type: "string" },
+			"map-settings": { describe: "path to file to use for map-settings", nargs: 1, type: "string" },
+			"keep-open": { describe: "Keep console open", nargs: 0, type: "boolean", default: false },
+		});
+	}],
+	handler: async function(
+		args: {
+			instance: string,
+			scenario: string,
+			seed?: number,
+			mapExchangeString?: string,
+			mapGenSettings?: string,
+			mapSettings?: string,
+			keepOpen: boolean,
+		},
+		control: Control) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		await control.setLogSubscriptions({ instanceIds: [instanceId] });
+		let { seed, mapGenSettings, mapSettings } = await loadMapSettings(args);
+		await control.sendTo(
+			{ instanceId },
+			new lib.InstanceLoadScenarioRequest(args.scenario, seed, mapGenSettings, mapSettings),
+		);
+		control.keepOpen = args.keepOpen;
+	},
+}));
+
+instanceCommands.add(new lib.Command({
+	definition: ["stop <instance>", "Stop instance", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to stop", type: "string" });
+	}],
+	handler: async function(args: { instance: string }, control: Control) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		await control.setLogSubscriptions({ instanceIds: [instanceId] });
+		await control.sendTo({ instanceId }, new lib.InstanceStopRequest());
+	},
+}));
+
+instanceCommands.add(new lib.Command({
+	definition: ["stop-all", "Stop all running instances", () => {}],
+	handler: async function(_args, control: Control) {
+		// Get all instances
+		const instances = await control.send(new lib.InstanceDetailsListRequest());
+
+		// Filter instances that should be stopped
+		const instancesToStop = instances
+			.filter((instance: lib.InstanceDetails) => ["starting", "running"].includes(instance.status));
+
+		if (instancesToStop.length === 0) {
+			print("No instances to stop.");
+			return;
+		}
+
+		print(`Stopping ${instancesToStop.length} instance(s):`);
+		for (const instance of instancesToStop) {
+			print(`  - ${instance.name} (ID: ${instance.id})`);
+		}
+
+		// Stop all filtered instances
+		const stopPromises = instancesToStop.map(async (instance: lib.InstanceDetails) => {
+			try {
+				await control.sendTo({ instanceId: instance.id }, new lib.InstanceStopRequest());
+				print(`✓ Stopped ${instance.name}`);
+			} catch (error) {
+				print(`✗ Failed to stop ${instance.name}: ${error}`);
+			}
+		});
+
+		await Promise.all(stopPromises);
+		print("Stop all operation completed.");
+	},
+}));
+
+instanceCommands.add(new lib.Command({
+	definition: ["kill <instance>", "Kill instance", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to kill", type: "string" });
+	}],
+	handler: async function(args: { instance: string }, control: Control) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		await control.setLogSubscriptions({ instanceIds: [instanceId] });
+		await control.sendTo({ instanceId }, new lib.InstanceKillRequest());
+	},
+}));
+
+instanceCommands.add(new lib.Command({
+	definition: ["delete <instance>", "Delete instance", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to delete", type: "string" });
+	}],
+	handler: async function(args: { instance: string }, control: Control) {
+		let instanceId = await lib.resolveInstance(control, args.instance);
+		await control.send(new lib.InstanceDeleteRequest(instanceId));
+	},
+}));
+
+instanceCommands.add(new lib.Command({
+	definition: ["send-rcon <instance> <command>", "Send RCON command", (yargs) => {
+		yargs.positional("instance", { describe: "Instance to send to", type: "string" });
+		yargs.positional("command", { describe: "command to send", type: "string" });
+	}],
+	handler: async function(args: { instance: string, command: string }, control: Control) {
+		let result = await control.sendTo(
+			{ instanceId: await lib.resolveInstance(control, args.instance) },
+			new lib.InstanceSendRconRequest(args.command),
+		);
+
+		// Factorio includes a newline in its response output.
+		process.stdout.write(result);
+	},
+}));
@@ -0,0 +1,90 @@
+import winston from "winston";
+
+import * as lib from "@clusterio/lib";
+import { ConsoleTransport, levels, logger } from "@clusterio/lib";
+import type { Control } from "../ctl";
+
+export const logCommands = new lib.CommandTree({ name: "log", description: "Log inspection" });
+logCommands.add(new lib.Command({
+	definition: ["follow", "follow cluster log", (yargs) => {
+		yargs.options({
+			"all": { describe: "Follow the whole cluster log", nargs: 0, type: "boolean", default: false },
+			"controller": { describe: "Follow log of the controller", nargs: 0, type: "boolean", default: false },
+			"host": { describe: "Follow log of given host", nargs: 1, type: "string", default: null },
+			"instance": { describe: "Follow log of given instance", nargs: 1, type: "string", default: null },
+		});
+	}],
+	handler: async function(
+		args: { all: boolean, controller: boolean, host: string | null, instance: string | null },
+		control: Control
+	) {
+		if (!args.all && !args.controller && !args.host && !args.instance) {
+			logger.error("At least one of --all, --controller, --host and --instance must be passed");
+			process.exitCode = 1;
+			return;
+		}
+		let instanceIds = args.instance ? [await lib.resolveInstance(control, args.instance)] : [];
+		let hostIds = args.host ? [await lib.resolveHost(control, args.host)] : [];
+		await control.setLogSubscriptions({ all: args.all, controller: args.controller, hostIds, instanceIds });
+		control.keepOpen = true;
+	},
+}));
+
+logCommands.add(new lib.Command({
+	definition: ["query", "Query cluster log", (yargs) => {
+		yargs.options({
+			"all": { describe: "Query the whole cluster log", nargs: 0, type: "boolean", default: false },
+			"controller": { describe: "Query log of the controller", nargs: 0, type: "boolean", default: false },
+			"host": { describe: "Query log of given host", nargs: 1, type: "string", default: null },
+			"instance": { describe: "Query log of given instance", nargs: 1, type: "string", default: null },
+			"max-level": { describe: "Maximum log level to return", nargs: 1, type: "string", default: undefined },
+			"limit": { describe: "Max number of entries to return", nargs: 1, type: "number", default: 1000 },
+			"start": { describe: "Limit from the start instead of the end", nargs: 0, type: "boolean", default: false },
+		});
+	}],
+	handler: async function(
+		args: {
+			all: boolean,
+			controller: boolean,
+			host: string | null,
+			instance: string | null,
+			maxLevel?: string,
+			limit: number,
+			start: boolean,
+		},
+		control: Control
+	) {
+		if (!args.all && !args.controller && !args.host && !args.instance) {
+			logger.error("At least one of --all, --controller, --host and --instance must be passed");
+			process.exitCode = 1;
+			return;
+		}
+		let instanceIds = args.instance ? [await lib.resolveInstance(control, args.instance)] : [];
+		let hostIds = args.host ? [await lib.resolveHost(control, args.host)] : [];
+		let result = await control.send(new lib.LogQueryRequest(
+			args.all,
+			args.controller,
+			hostIds,
+			instanceIds,
+			args.maxLevel as keyof typeof levels,
+			args.limit,
+			args.start ? "asc" : "desc",
+		));
+
+		if (!args.start) {
+			result.log.reverse();
+		}
+
+		let stdoutLogger = winston.createLogger({
+			level: "verbose",
+			levels,
+			format: new lib.TerminalFormat({ showTimestamp: true }),
+			transports: [
+				new ConsoleTransport({ errorLevels: [], warnLevels: [] }),
+			],
+		});
+		for (let info of result.log) {
+			stdoutLogger.log(info as any);
+		}
+	},
+}));
@@ -0,0 +1,237 @@
+import fs from "fs-extra";
+import asTableModule from "as-table";
+import events from "events";
+import path from "path";
+import stream from "stream";
+import util from "util";
+
+import * as lib from "@clusterio/lib";
+import { logger } from "@clusterio/lib";
+import type { Control } from "../ctl";
+import { print } from "./command_ops";
+
+const asTable = asTableModule.configure({ delimiter: " | " });
+const finished = util.promisify(stream.finished);
+
+export const modCommands = new lib.CommandTree({ name: "mod", description: "Manage uploaded mods" });
+modCommands.add(new lib.Command({
+	definition: ["show <name> <mod-version>", "Show details for a mod stored in the cluster", (yargs) => {
+		yargs.positional("name", { describe: "Mod name to show details for", type: "string" });
+		yargs.positional("mod-version", { describe: "Version of the mod", type: "string" });
+	}],
+	handler: async function(args: { name: string, modVersion: string }, control: Control) {
+		if (!lib.isFullVersion(args.modVersion)) {
+			throw new lib.CommandError("mod-version must match format digit.digit.digit");
+		}
+		let modInfo = await control.send(new lib.ModGetRequest(args.name, args.modVersion));
+		for (let [field, value] of Object.entries(modInfo)) {
+			if (value instanceof Array) {
+				print(`${field}:`);
+				for (let entry of value) {
+					print(`  ${entry}`);
+				}
+			} else {
+				print(`${field}: ${value}`);
+			}
+		}
+	},
+}));
+
+modCommands.add(new lib.Command({
+	definition: [["list", "l"], "List mods stored in the cluster", (yargs) => {
+		yargs.options({
+			"fields": {
+				describe: "Fields to show, supports 'all'.",
+				array: true,
+				type: "string",
+				default: ["name", "version", "title", "factorio_version"],
+			},
+		});
+	}],
+	handler: async function(args: { fields: string[] }, control: Control) {
+		let mods = await control.send(new lib.ModListRequest());
+		if (!args.fields.includes("all")) {
+			for (let entry of mods) {
+				for (let field of Object.keys(entry)) {
+					if (!args.fields.includes(field)) {
+						// @ts-expect-error terrible hack
+						delete entry[field];
+					}
+				}
+			}
+		}
+		print(asTable(mods));
+	},
+}));
+
+modCommands.add(new lib.Command({
+	definition: ["search <factorio-version> [query]", "Search mods stored in the cluster", (yargs) => {
+		yargs.positional("factorio-version", { describe: "Major version of Factorio to search for", type: "string" });
+		yargs.positional("query", { describe: "Search query", type: "string", default: "" });
+		yargs.options({
+			"page": {
+				describe: "Result page to show",
+				type: "number",
+				default: 1,
+			},
+			"page-size": {
+				describe: "Results per page to show",
+				type: "number",
+				default: 10,
+			},
+			"sort": {
+				describe: "sort results by given field",
+				type: "string",
+			},
+			"sort-order": {
+				describe: "order to sort results in (asc/desc)",
+				type: "string",
+				default: "asc",
+			},
+			"fields": {
+				describe: "Fields to show, supports 'all'.",
+				array: true,
+				type: "string",
+				default: ["name", "version", "title", "factorio_version"],
+			},
+		});
+	}],
+	handler: async function(
+		args: {
+			factorioVersion: string,
+			query: string,
+			page: number,
+			pageSize: number,
+			sort?: string,
+			sortOrder: "asc" | "desc",
+			fields: string[],
+		},
+		control: Control
+	) {
+		let response = await control.send(new lib.ModSearchRequest(
+			args.query,
+			lib.normaliseApiVersion(args.factorioVersion as any),
+			args.page,
+			args.pageSize,
+			args.sort,
+			args.sortOrder
+		));
+		let results = response.results.flatMap(result => result.versions);
+		if (!args.fields.includes("all")) {
+			for (let entry of results) {
+				for (let field of Object.keys(entry)) {
+					if (!args.fields.includes(field)) {
+						// @ts-expect-error terrible hack
+						delete entry[field];
+					}
+				}
+			}
+		}
+		for (let issue of response.queryIssues) {
+			print(issue);
+		}
+		print(`page ${args.page} of ${response.pageCount} (${response.resultCount} results)`);
+		print(asTable(results));
+	},
+}));
+
+modCommands.add(new lib.Command({
+	definition: ["upload <file>", "Upload mod to the cluster", (yargs) => {
+		yargs.positional("file", { describe: "File to upload", type: "string" });
+	}],
+	handler: async function(args: { file: string }, control: Control) {
+		let filename = path.basename(args.file);
+		if (!filename.endsWith(".zip")) {
+			throw new lib.CommandError("Mod filename must end with .zip");
+		}
+
+		let url = new URL(control.config.get("control.controller_url")!);
+		url.pathname += "api/upload-mod";
+		url.searchParams.append("filename", filename);
+
+		let response = await fetch(url, {
+			method: "POST",
+			body: fs.createReadStream(args.file),
+			duplex: "half",
+			headers: {
+				"X-Access-Token": control.config.get("control.controller_token")!,
+				"Content-Type": "application/zip",
+			},
+		});
+
+		type ResponseType = { errors?: [], request_errors?: [], mods: Parameters<typeof lib.ModInfo.fromJSON>[0][]};
+		const result = await response.json() as ResponseType;
+
+		for (let error of result.errors || []) {
+			logger.error(error);
+		}
+
+		for (let requestError of result.request_errors || []) {
+			logger.error(requestError);
+		}
+
+		if (result.mods && result.mods.length) {
+			const mod = lib.ModInfo.fromJSON(result.mods[0]);
+			logger.info(`Successfully uploaded ${mod.filename}`);
+		}
+
+		if ((result.errors || []).length || (result.request_errors || []).length) {
+			throw new lib.CommandError("Uploading mod failed");
+		}
+	},
+}));
+
+modCommands.add(new lib.Command({
+	definition: ["download <name> <mod-version>", "Download a mod from the cluster", (yargs) => {
+		yargs.positional("name", { describe: "Internal name of mod to download", type: "string" });
+		yargs.positional("mod-version", { describe: "Version of mod to download", type: "string" });
+	}],
+	handler: async function(args: { name: string, modVersion: string }, control: Control) {
+		if (!lib.isFullVersion(args.modVersion)) {
+			throw new lib.CommandError("mod-version must match format digit.digit.digit");
+		}
+		let streamId = await control.send(new lib.ModDownloadRequest(args.name, args.modVersion));
+
+		let url = new URL(control.config.get("control.controller_url")!);
+		url.pathname += `api/stream/${streamId}`;
+		let response = await fetch(url);
+		if (!response.body) {
+			throw new lib.CommandError("Got empty response from server");
+		}
+
+		let writeStream;
+		let filename = `${args.name}_${args.modVersion}.zip`;
+		let tempFilename = filename.replace(/(\.zip)?$/, ".tmp.zip");
+		while (true) {
+			try {
+				writeStream = fs.createWriteStream(tempFilename, { flags: "wx" });
+				await events.once(writeStream, "open");
+				break;
+			} catch (err: any) {
+				if (err.code === "EEXIST") {
+					tempFilename = await lib.findUnusedName(".", tempFilename, ".tmp.zip");
+				} else {
+					throw err;
+				}
+			}
+		}
+		stream.Readable.fromWeb(response.body).pipe(writeStream);
+		await finished(writeStream);
+		await fs.rename(tempFilename, filename);
+
+		logger.info(`Downloaded ${filename}`);
+	},
+}));
+
+modCommands.add(new lib.Command({
+	definition: ["delete <name> <mod-version>", "Delete a mod stored in the cluster", (yargs) => {
+		yargs.positional("name", { describe: "Name of mod to delete", type: "string" });
+		yargs.positional("mod-version", { describe: "Version of mod to delete", type: "string" });
+	}],
+	handler: async function(args: { name: string, modVersion: string }, control: Control) {
+		if (!lib.isFullVersion(args.modVersion)) {
+			throw new lib.CommandError("mod-version must match format digit.digit.digit");
+		}
+		await control.send(new lib.ModDeleteRequest(args.name, args.modVersion));
+	},
+}));
@@ -0,0 +1,315 @@
+import asTableModule from "as-table";
+
+import * as lib from "@clusterio/lib";
+import { logger } from "@clusterio/lib";
+import type { Control } from "../ctl";
+import { print } from "./command_ops";
+
+const asTable = asTableModule.configure({ delimiter: " | " });
+
+export const modPackCommands = new lib.CommandTree({ name: "mod-pack", description: "Mod Pack" });
+modPackCommands.add(new lib.Command({
+	definition: ["show <mod-pack>", "Show details of mod pack", (yargs) => {
+		yargs.positional("mod-pack", { describe: "Mod pack to show", type: "string" });
+	}],
+	handler: async function(args: { modPack: string }, control: Control) {
+		let mods = new Map(
+			(await control.send(new lib.ModListRequest())).map(m => [m.id, m])
+		);
+		let modPack = await control.send(
+			new lib.ModPackGetRequest(await lib.resolveModPack(control, args.modPack))
+		);
+
+		for (let [field, value] of Object.entries(modPack)) {
+			if (field === "mods") {
+				print(`${field}:`);
+				for (let [name, entry] of value) {
+					const mod = mods.get(`${name}_${entry.version}`);
+					const missing = !mod && "? ";
+					const badChecksum = mod && entry.sha1 && entry.sha1 !== mod.sha1 && "! ";
+					const warn = missing || badChecksum || "";
+					const enabled = entry.enabled ? "" : "(disabled) ";
+					print(`  ${warn}${enabled}${name} ${entry.version}${entry.sha1 ? ` (${entry.sha1})` : ""}`);
+				}
+			} else if (field === "settings") {
+				print(`${field}:`);
+				for (let [scope, settings] of Object.entries(value)) {
+					print(`  ${scope}:`);
+					for (let [setting, settingValue] of settings as any) {
+						print(`    ${setting}: ${JSON.stringify(settingValue.value)}`);
+					}
+				}
+			} else if (field === "exportManifest") {
+				print(`${field}:`);
+				if (value && value.assets) {
+					print("  assets:");
+					for (let [name, fileName] of Object.entries(value.assets)) {
+						print(`    ${name}: ${fileName}`);
+					}
+				}
+
+			} else {
+				print(`${field}: ${value}`);
+			}
+		}
+	},
+}));
+
+modPackCommands.add(new lib.Command({
+	definition: [["list", "l"], "List mod packs in the cluster"],
+	handler: async function(args: object, control: Control) {
+		let modPacks = await control.send(new lib.ModPackListRequest());
+		let fields = ["id", "name", "factorioVersion"];
+		for (let entry of modPacks) {
+			for (let field of Object.keys(entry)) {
+				if (!fields.includes(field)) {
+					// @ts-expect-error terrible hack
+					delete entry[field];
+				}
+			}
+		}
+		print(asTable(modPacks));
+	},
+}));
+
+function setModPackSettings(
+	modPack: lib.ModPack,
+	args: {
+		boolSetting?: string[],
+		intSetting?: string[],
+		doubleSetting?: string[],
+		stringSetting?: string[],
+		colorSetting?: string[],
+	},
+) {
+	function doSettings(settings: string[], cast: (value: string) => (string | number | boolean)) {
+		for (let i = 0; i + 2 < settings.length; i += 3) {
+			const [scope, name, value] = settings.slice(i, i + 3);
+			if (!["startup", "runtime-global", "runtime-per-user"].includes(scope)) {
+				throw new lib.CommandError(
+					`Setting scope must be one of startup, runtime-gloabl, or runtime-per-user, not ${scope}`
+				);
+			}
+			const checkedScope = scope as "startup" | "runtime-global" | "runtime-per-user";
+			modPack.settings[checkedScope].set(name, { value: cast(value) });
+		}
+	}
+
+	doSettings(args.boolSetting || [], value => {
+		if (!["true", "false"].includes(value)) {
+			throw new lib.CommandError(`boolean value must be one of true or false, not ${value}`);
+		}
+		return value === "true";
+	});
+	doSettings(args.intSetting || [], value => {
+		// eslint-disable-next-line radix
+		let number = Number.parseInt(value);
+		if (isNaN(number)) {
+			throw new lib.CommandError(`int value must be an integer, not ${value}`);
+		}
+		return number;
+	});
+	doSettings(args.doubleSetting || [], value => {
+		let number = Number.parseFloat(value);
+		if (isNaN(number)) {
+			throw new lib.CommandError(`double value must be a number, not ${value}`);
+		}
+		return number;
+	});
+	doSettings(args.stringSetting || [], value => value);
+	doSettings(args.colorSetting || [], value => {
+		let color = JSON.parse(value);
+		if (typeof color !== "object" || color === null) {
+			throw new lib.CommandError("color value must be a JSON object with r, g, b, a properties");
+		}
+		return color;
+	});
+}
+
+function setModPackMods(modPack: lib.ModPack, mods: string[] | undefined) {
+	for (let mod of mods || []) {
+		const [name, version, sha1] = mod.split(":");
+		if (!version) {
+			throw new lib.CommandError("Added mod must be formatted as name:version or name:version:sha1");
+		}
+		if (!lib.isFullVersion(version)) {
+			throw new lib.CommandError("version must match the format digit.digit.digit");
+		}
+		if (sha1 && !/^[0-9a-f]{40}$/.test(sha1)) {
+			throw new lib.CommandError("sha1 must be a 40 digit lower case hex string");
+		}
+		modPack.mods.set(name, { name, enabled: true, version, sha1 });
+	}
+}
+
+function setModPackModsEnabled(modPack: lib.ModPack, mods: string[] | undefined, enabled: boolean) {
+	for (let mod of mods || []) {
+		if (!modPack.mods.has(mod)) {
+			throw new lib.CommandError(`Mod named ${mod} does not exist in the mod pack`);
+		}
+		modPack.mods.get(mod)!.enabled = enabled;
+	}
+}
+
+modPackCommands.add(new lib.Command({
+	definition: ["create <name> <factorio-version>", "Create mod pack", (yargs) => {
+		yargs.positional("name", { describe: "Name of mod pack to create", type: "string" });
+		yargs.positional("factorio-version", { describe: "Version of factorio the mod pack is for", type: "string" });
+		yargs.options({
+			"description": { describe: "Description for mod pack", type: "string" },
+			"mods": { describe: "Mods in the form of name:version[:sha1]", array: true, type: "string" },
+			"disabled-mods": { describe: "Mods that are in the pack but not enabled", array: true, type: "string" },
+			"bool-setting": { describe: "Set boolean setting", array: true, nargs: 3, type: "string" },
+			"int-setting": { describe: "Set int setting", array: true, nargs: 3, type: "string" },
+			"double-setting": { describe: "Set double setting", array: true, nargs: 3, type: "string" },
+			"string-setting": { describe: "Set string setting", array: true, nargs: 3, type: "string" },
+			"color-setting": { describe: "Set color setting", array: true, nargs: 3, type: "string" },
+		});
+	}],
+	handler: async function(
+		args: {
+			name: string,
+			factorioVersion: string,
+			description?: string,
+			mods?: string[],
+			disabledMods?: string[],
+			boolSetting?: string[],
+			intSetting?: string[],
+			doubleSetting?: string[],
+			stringSetting?: string[],
+			colorSetting?: string[],
+		},
+		control: Control,
+	) {
+		const modPack = new lib.ModPack();
+		modPack.name = args.name;
+		if (args.description) { modPack.description = args.description; }
+		if (args.factorioVersion) {
+			if (!lib.isPartialVersion(args.factorioVersion)) {
+				throw new lib.CommandError("factorio-version must match the format digit.digit[.digit]");
+			}
+			modPack.factorioVersion = args.factorioVersion;
+		}
+		setModPackMods(modPack, args.mods);
+		setModPackModsEnabled(modPack, args.disabledMods, false);
+		setModPackSettings(modPack, args);
+		await control.send(new lib.ModPackCreateRequest(modPack));
+		print(`Created mod pack ${modPack.name} (${modPack.id})`);
+	},
+}));
+
+modPackCommands.add(new lib.Command({
+	definition: ["import <string>", "Import mod pack string", (yargs) => {
+		yargs.positional("string", { describe: "Mod pack string to import", type: "string" });
+	}],
+	handler: async function(args: { string: string }, control: Control) {
+		const modPack = lib.ModPack.fromModPackString(args.string);
+		await control.send(new lib.ModPackCreateRequest(modPack));
+		print(`Created mod pack ${modPack.name} (${modPack.id})`);
+	},
+}));
+
+modPackCommands.add(new lib.Command({
+	definition: ["export <mod-pack>", "Export mod pack string", (yargs) => {
+		yargs.positional("string", { describe: "Mod pack to export", type: "string" });
+	}],
+	handler: async function(args: { modPack: string }, control: Control) {
+		const modPack = await control.send(
+			new lib.ModPackGetRequest(await lib.resolveModPack(control, args.modPack))
+		);
+		print(modPack.toModPackString());
+	},
+}));
+
+modPackCommands.add(new lib.Command({
+	definition: ["edit <mod-pack>", "Edit mod pack", (yargs) => {
+		yargs.positional("mod-pack", { describe: "Mod pack to remove from", type: "string" });
+		yargs.options({
+			"name": { describe: "New name for mod pack", type: "string" },
+			"description": { describe: "New description for mod pack", type: "string" },
+			"factorio-version": { describe: "Set version of factorio the mod pack is for", type: "string" },
+			"add-mods": { describe: "Mods in the form of name:version[:sha1] to add", array: true, type: "string" },
+			"enable-mods": { describe: "Mods to set as enabled", array: true, type: "string" },
+			"disable-mods": { describe: "Mods to set as disabled", array: true, type: "string" },
+			"remove-mods": { describe: "Name of mods to remove", array: true, type: "string" },
+			"bool-setting": { describe: "Set boolean setting", array: true, nargs: 3, type: "string" },
+			"int-setting": { describe: "Set int setting", array: true, nargs: 3, type: "string" },
+			"double-setting": { describe: "Set double setting", array: true, nargs: 3, type: "string" },
+			"string-setting": { describe: "Set string setting", array: true, nargs: 3, type: "string" },
+			"color-setting": { describe: "Set color setting", array: true, nargs: 3, type: "string" },
+			"remove-setting": { describe: "Remove a setting", array: true, nargs: 2, type: "string" },
+		});
+	}],
+	handler: async function(
+		args: {
+			modPack: string,
+			name?: string,
+			description?: string,
+			factorioVersion?: string,
+			addMods?: string[],
+			enableMods?: string[],
+			disableMods?: string[],
+			removeMods?: string[],
+			boolSetting?: string[],
+			intSetting?: string[],
+			doubleSetting?: string[],
+			stringSetting?: string[],
+			colorSetting?: string[],
+			removeSetting?: string[],
+		},
+		control: Control,
+	) {
+		const modPack = await control.send(
+			new lib.ModPackGetRequest(await lib.resolveModPack(control, args.modPack))
+		);
+
+		if (args.name) { modPack.name = args.name; }
+		if (args.description) { modPack.description = args.description; }
+		if (args.factorioVersion) {
+			if (!lib.isPartialVersion(args.factorioVersion)) {
+				throw new lib.CommandError("factorio-version must match the format digit.digit[.digit]");
+			}
+			modPack.factorioVersion = args.factorioVersion;
+		}
+
+		setModPackMods(modPack, args.addMods);
+		for (let name of args.removeMods || []) {
+			if (modPack.mods.has(name)) {
+				modPack.mods.delete(name);
+			} else {
+				logger.warn(`Mod ${name} did not exist on ${modPack.name}`);
+			}
+		}
+		setModPackModsEnabled(modPack, args.disableMods, false);
+		setModPackModsEnabled(modPack, args.enableMods, true);
+
+		setModPackSettings(modPack, args);
+		if (args.removeSetting) {
+			for (let i = 0; i + 1 < args.removeSetting.length; i += 2) {
+				const [scope, name] = args.removeSetting.slice(i, i + 2);
+				if (!["startup", "runtime-global", "runtime-per-user"].includes(scope)) {
+					throw new lib.CommandError(
+						`Setting scope must be one of startup, runtime-gloabl, or runtime-per-user, not ${scope}`
+					);
+				}
+				const checkedScope = scope as "startup" | "runtime-global" | "runtime-per-user";
+				if (modPack.settings[checkedScope].has(name)) {
+					modPack.settings[checkedScope].delete(name);
+				} else {
+					logger.warn(`Mod setting ${scope} ${name} did not exist on ${modPack.name}`);
+				}
+			}
+		}
+		await control.send(new lib.ModPackUpdateRequest(modPack));
+	},
+}));
+
+modPackCommands.add(new lib.Command({
+	definition: ["delete <mod-pack>", "Delete mod pack", (yargs) => {
+		yargs.positional("mod-pack", { describe: "Mod pack to delete", type: "string" });
+	}],
+	handler: async function(args: { modPack: string }, control: Control) {
+		const id = await lib.resolveModPack(control, args.modPack);
+		await control.send(new lib.ModPackDeleteRequest(id));
+	},
+}));
@@ -0,0 +1,16 @@
+import asTableModule from "as-table";
+
+import * as lib from "@clusterio/lib";
+import type { Control } from "../ctl";
+import { print } from "./command_ops";
+
+const asTable = asTableModule.configure({ delimiter: " | " });
+
+export const permissionCommands = new lib.CommandTree({ name: "permission", description: "Permission inspection" });
+permissionCommands.add(new lib.Command({
+	definition: [["list", "l"], "List permissions in the cluster"],
+	handler: async function(args: object, control: Control) {
+		let permissions = await control.send(new lib.PermissionListRequest());
+		print(asTable(permissions));
+	},
+}));
@@ -0,0 +1,100 @@
+import asTableModule from "as-table";
+
+import * as lib from "@clusterio/lib";
+import { logger } from "@clusterio/lib";
+import type { Control } from "../ctl";
+import { print } from "./command_ops";
+
+const asTable = asTableModule.configure({ delimiter: " | " });
+
+export const roleCommands = new lib.CommandTree({ name: "role", description: "Role management" });
+roleCommands.add(new lib.Command({
+	definition: [["list", "l"], "List roles in the cluster"],
+	handler: async function(args: object, control: Control) {
+		let roles = await control.send(new lib.RoleListRequest());
+		print(asTable(roles));
+	},
+}));
+
+roleCommands.add(new lib.Command({
+	definition: ["create <name>", "Create a new role", (yargs) => {
+		yargs.positional("name", { describe: "Name of role to create", type: "string" });
+		yargs.options({
+			"description": { describe: "Description for role", nargs: 1, type: "string", default: "" },
+			"permissions": { describe: "Permissions role grants", nargs: 1, array: true, type: "string", default: [] },
+		});
+	}],
+	handler: async function(args: { name: string, description: string, permissions: string[] }, control: Control) {
+		let id = await control.send(new lib.RoleCreateRequest(
+			args.name,
+			args.description,
+			args.permissions,
+		));
+		logger.info(`Created role ID ${id}`);
+	},
+}));
+
+roleCommands.add(new lib.Command({
+	definition: ["edit <role>", "Edit existing role", (yargs) => {
+		yargs.positional("role", { describe: "Role to edit", type: "string" });
+		yargs.options({
+			"name": { describe: "New name for role", nargs: 1, type: "string" },
+			"description": { describe: "New description for role", nargs: 1, type: "string" },
+			"set-perms": { describe: "Set permissions for role", array: true, type: "string" },
+			"add-perms": { describe: "Add permissions to role", array: true, type: "string", conflicts: "set-perms" },
+			"remove-perms": {
+				describe: "Remove permissions from role", array: true, type: "string", conflicts: "set-perms",
+			},
+			"grant-default": { describe: "Add default permissions to role", nargs: 0, type: "boolean" },
+		});
+	}],
+	handler: async function(
+		args: {
+			role: string,
+			name?: string,
+			description?: string,
+			setPerms?: string[],
+			addPerms?: string[],
+			removePerms?: string[],
+			grantDefault?: boolean,
+		},
+		control: Control
+	) {
+		let role = await lib.retrieveRole(control, args.role);
+
+		if (args.name !== undefined) {
+			role.name = args.name;
+		}
+		if (args.description !== undefined) {
+			role.description = args.description;
+		}
+		if (args.addPerms) {
+			for (const perm of args.addPerms) {
+				role.permissions.add(perm);
+			}
+		}
+		if (args.removePerms) {
+			for (let perm of args.removePerms) {
+				role.permissions.delete(perm);
+			}
+		}
+		if (args.setPerms !== undefined) {
+			role.permissions = new Set(args.setPerms);
+		}
+		await control.send(new lib.RoleUpdateRequest(role.id, role.name, role.description, [...role.permissions]));
+
+		if (args.grantDefault) {
+			await control.send(new lib.RoleGrantDefaultPermissionsRequest(role.id));
+		}
+	},
+}));
+
+roleCommands.add(new lib.Command({
+	definition: ["delete <role>", "Delete role", (yargs) => {
+		yargs.positional("role", { describe: "Role to delete", type: "string" });
+	}],
+	handler: async function(args: { role: string }, control: Control) {
+		let role = await lib.retrieveRole(control, args.role);
+		await control.send(new lib.RoleDeleteRequest(role.id));
+	},
+}));
@@ -0,0 +1,304 @@
+import fs from "fs-extra";
+import asTableModule from "as-table";
+import path from "path";
+
+import * as lib from "@clusterio/lib";
+import type { Control } from "../ctl";
+import { print } from "./command_ops";
+
+const asTable = asTableModule.configure({ delimiter: " | " });
+
+export const userCommands = new lib.CommandTree({ name: "user", alias: ["u"], description: "User management" });
+userCommands.add(new lib.Command({
+	definition: ["show <name>", "Show details for one user", (yargs) => {
+		yargs.positional("name", { decribe: "Name of user to show", type: "string" });
+		yargs.options({
+			"instance-stats": { describe: "include per-instance stats", nargs: 0, type: "boolean", default: false },
+		});
+	}],
+	handler: async function(args: { name: string, instanceStats: boolean }, control: Control) {
+		let user = await control.send(new lib.UserGetRequest(args.name));
+		Object.assign(user, user.playerStats);
+		// @ts-expect-error Terrible hack
+		delete user.playerStats;
+		let instanceStats = user.instanceStats;
+		// @ts-expect-error Terrible hack
+		delete user.instanceStats;
+		print(asTable(Object.entries(user).map(([property, value]) => ({ property, value }))));
+
+		if (args.instanceStats) {
+			let instances = await control.send(new lib.InstanceDetailsListRequest());
+			function instanceName(id: number) {
+				let instance = instances.find(i => i.id === id);
+				if (instance) {
+					return instance.name;
+				}
+				return "<deleted>";
+			}
+			for (let [id, playerInstanceStats] of instanceStats || []) {
+				print();
+				print(`Instance ${instanceName(id)} (${id}):`);
+				print(asTable(Object.entries(playerInstanceStats).map(([property, value]) => ({ property, value }))));
+			}
+		}
+	},
+}));
+
+userCommands.add(new lib.Command({
+	definition: [["list", "l"], "List user in the cluster", (yargs) => {
+		yargs.options({
+			"stats": { describe: "include user stats", nargs: 0, type: "boolean", default: false },
+			"attributes": { describe: "include admin/whitelisted/banned", nargs: 0, type: "boolean", default: false },
+		});
+	}],
+	handler: async function(args: { stats: boolean, attributes: boolean }, control: Control) {
+		let users = await control.send(new lib.UserListRequest());
+		for (let user of users) {
+			if (args.stats) {
+				Object.assign(user, user.playerStats);
+			}
+			// @ts-expect-error Terrible hack
+			delete user.playerStats;
+			// @ts-expect-error Terrible hack
+			delete user.isDeleted;
+			// @ts-expect-error Terrible hack
+			delete user.banReason;
+			// @ts-expect-error Terrible hack
+			delete user.instanceStats;
+			if (!args.attributes) {
+				// @ts-expect-error Terrible hack
+				delete user.isAdmin;
+				// @ts-expect-error Terrible hack
+				delete user.isWhitelisted;
+				// @ts-expect-error Terrible hack
+				delete user.isBanned;
+			}
+		}
+		print(asTable(users));
+	},
+}));
+
+userCommands.add(new lib.Command({
+	definition: ["create <name>", "Create a user", (yargs) => {
+		yargs.positional("name", { describe: "Name of user to create", type: "string" });
+	}],
+	handler: async function(args: { name: string }, control: Control) {
+		await control.send(new lib.UserCreateRequest(args.name));
+	},
+}));
+
+userCommands.add(new lib.Command({
+	definition: ["revoke-token <name>", "Revoke token for user", (yargs) => {
+		yargs.positional("name", { describe: "Name of user to revoke token for", type: "string" });
+	}],
+	handler: async function(args: { name: string }, control: Control) {
+		await control.send(new lib.UserRevokeTokenRequest(args.name));
+	},
+}));
+
+userCommands.add(new lib.Command({
+	definition: ["set-admin <user>", "Promote or demote a user to admin", (yargs) => {
+		yargs.positional("user", { describe: "Name of user set admin status for", type: "string" });
+		yargs.options({
+			"revoke": { describe: "Revoke admin status", nargs: 0, type: "boolean", default: false },
+			"create": { describe: "Create user if it does not exist", nargs: 0, type: "boolean", default: false },
+		});
+	}],
+	handler: async function(args: { user: string, revoke: boolean, create: boolean }, control: Control) {
+		await control.send(new lib.UserSetAdminRequest(args.user, args.create, !args.revoke));
+	},
+}));
+
+userCommands.add(new lib.Command({
+	definition: ["set-whitelisted <user>", "Add or remove user from the whitelist", (yargs) => {
+		yargs.positional("user", { describe: "Name of user to set whitelist status for", type: "string" });
+		yargs.options({
+			"remove": { describe: "Remove from whitelist", nargs: 0, type: "boolean", default: false },
+			"create": { describe: "Create user if it does not exist", nargs: 0, type: "boolean", default: false },
+		});
+	}],
+	handler: async function(args: { user: string, remove: boolean, create: boolean }, control: Control) {
+		await control.send(new lib.UserSetWhitelistedRequest(args.user, args.create, !args.remove));
+	},
+}));
+
+userCommands.add(new lib.Command({
+	definition: ["set-banned <user>", "Ban or pardon user from banlist", (yargs) => {
+		yargs.positional("user", { describe: "Name of user to set ban status for", type: "string" });
+		yargs.options({
+			"pardon": { describe: "Remove from banlist", nargs: 0, type: "boolean", default: false },
+			"reason": { describe: "Ban reason", nargs: 1, type: "string", default: "" },
+			"create": { describe: "Create user if it does not exist", nargs: 0, type: "boolean", default: false },
+		});
+	}],
+	handler: async function(
+		args: {
+			user: string,
+			pardon: boolean,
+			reason: string,
+			create: boolean
+		},
+		control: Control
+	) {
+		await control.send(new lib.UserSetBannedRequest(args.user, args.create, !args.pardon, args.reason));
+	},
+}));
+
+userCommands.add(new lib.Command({
+	definition: ["set-roles <user> [roles...]", "Replace user roles", (yargs) => {
+		yargs.positional("user", { describe: "Name of user to change roles for", type: "string" });
+		yargs.positional("roles", { describe: "roles to assign", type: "string" });
+	}],
+	handler: async function(args: { user: string, roles: string[] }, control: Control) {
+		let roles = await control.send(new lib.RoleListRequest());
+
+		let resolvedRoles = [];
+		for (let roleName of args.roles) {
+			if (/^-?\d+$/.test(roleName)) {
+				let roleId = parseInt(roleName, 10);
+				resolvedRoles.push(roleId);
+
+			} else {
+				let found = false;
+				for (let role of roles) {
+					if (role.name === roleName) {
+						resolvedRoles.push(role.id);
+						found = true;
+						break;
+					}
+				}
+
+				if (!found) {
+					throw new lib.CommandError(`No role named ${roleName}`);
+				}
+			}
+		}
+
+		await control.send(new lib.UserUpdateRolesRequest(args.user, resolvedRoles));
+	},
+}));
+
+userCommands.add(new lib.Command({
+	definition: ["delete <user>", "Delete user", (yargs) => {
+		yargs.positional("user", { describe: "Name of user to delete", type: "string" });
+	}],
+	handler: async function(args: { user: string }, control: Control) {
+		await control.send(new lib.UserDeleteRequest(args.user));
+	},
+}));
+
+async function handleImportOrRestore(args: {
+	filepath: string,
+	users: boolean,
+	bans: boolean,
+	admins: boolean,
+	whitelist: boolean,
+	noBackup?: boolean,
+}, control: Control, restore: boolean) {
+	let importType: ConstructorParameters<typeof lib.UserBulkImportRequest>[0];
+	const data = JSON.parse((await fs.readFile(args.filepath)).toString());
+	const optionCount = [args.users, args.bans, args.admins, args.whitelist]
+		.reduce((acc, bool) => (bool ? acc + 1 : acc), 0);
+
+	if (optionCount > 1) {
+		throw new lib.CommandError("Can not specify multiple options");
+	}
+
+	// Assign based on options or attempt to guess based on filename
+	const filename = path.basename(args.filepath);
+	if (args.users || (optionCount === 0 && data.export_version)) {
+		importType = "users";
+	} else if (args.bans || (optionCount === 0 && filename.includes("ban"))) {
+		importType = "bans";
+	} else if (args.admins || (optionCount === 0 && filename.includes("admin"))) {
+		importType = "admins";
+	} else if (args.whitelist || (optionCount === 0 && filename.includes("whitelist"))) {
+		importType = "whitelist";
+	} else {
+		throw new lib.CommandError("Unknown json file, please specify an option");
+	}
+
+	const backup = await control.send(
+		new lib.UserBulkImportRequest(importType, importType === "users" ? data.users : data, restore)
+	);
+
+	print(`${restore ? "Restored" : "Imported"} ${importType} from ${args.filepath}`);
+	if (restore && backup && !args.noBackup) {
+		await fs.writeJSON(`${importType}-backup.json`, backup, { spaces: 2 });
+		print(`Wrote backup to ${importType}-backup.json`);
+	}
+}
+
+userCommands.add(new lib.Command({
+	definition: ["import <filepath>", "Import user data from a file", (yargs) => {
+		yargs.positional("filepath", { describe: "Path to the file to import", type: "string" });
+		yargs.options({
+			"users": { describe: "Import users json", nargs: 0, type: "boolean", default: false },
+			"bans": { describe: "Import banlist json", nargs: 0, type: "boolean", default: false },
+			"admins": { describe: "Import adminlist json", nargs: 0, type: "boolean", default: false },
+			"whitelist": { describe: "Import whitelist json", nargs: 0, type: "boolean", default: false },
+		});
+	}],
+	handler: async function(args: any, control: any) {
+		await handleImportOrRestore(args, control, false);
+	},
+}));
+
+userCommands.add(new lib.Command({
+	definition: ["restore <filepath>", "Restore user data from a file", (yargs) => {
+		yargs.positional("filepath", { describe: "Path to the file to import", type: "string" });
+		yargs.options({
+			"users": { describe: "Restore users json", nargs: 0, type: "boolean", default: false },
+			"bans": { describe: "Restore banlist json", nargs: 0, type: "boolean", default: false },
+			"admins": { describe: "Restore adminlist json", nargs: 0, type: "boolean", default: false },
+			"whitelist": { describe: "Restore whitelist json", nargs: 0, type: "boolean", default: false },
+			"no-backup": { describe: "Don't save a backup to the cwd", nargs: 0, type: "boolean", default: false },
+		});
+	}],
+	handler: async function(args: any, control: any) {
+		await handleImportOrRestore(args, control, true);
+	},
+}));
+
+userCommands.add(new lib.Command({
+	definition: ["export <filepath>", "Export user data to a file", (yargs) => {
+		yargs.positional("filepath", { describe: "Path to the file to save to", type: "string" });
+		yargs.options({
+			"users": { describe: "Export users json", nargs: 0, type: "boolean", default: false },
+			"bans": { describe: "Export banlist json", nargs: 0, type: "boolean", default: false },
+			"admins": { describe: "Export adminlist json", nargs: 0, type: "boolean", default: false },
+			"whitelist": { describe: "Export whitelist json", nargs: 0, type: "boolean", default: false },
+		});
+	}],
+	handler: async function(args: {
+		filepath: string,
+		users: boolean,
+		bans: boolean,
+		admins: boolean,
+		whitelist: boolean,
+	}, control: Control) {
+		let exportType = "users" as ConstructorParameters<typeof lib.UserBulkExportRequest>[0];
+		const optionCount = [args.bans, args.admins, args.whitelist]
+			.reduce((acc, bool) => (bool ? acc + 1 : acc), 0);
+
+		if (optionCount > 1) {
+			throw new lib.CommandError("Can not specify multiple options");
+		}
+
+		// Assign based on options or attempt to guess based on filename
+		if (args.users) {
+			exportType = "users";
+		} else if (args.bans) {
+			exportType = "bans";
+		} else if (args.admins) {
+			exportType = "admins";
+		} else if (args.whitelist) {
+			exportType = "whitelist";
+		}
+
+		await fs.writeJSON(args.filepath, await control.send(
+			new lib.UserBulkExportRequest(exportType)
+		), { spaces: 2 });
+		print(`Exported ${exportType} to ${args.filepath}`);
+	},
+}));
@@ -0,0 +1,58 @@
+import * as lib from "@clusterio/lib";
+
+export async function getEditor(argsEditor: string) {
+	// eslint-disable-next-line
+	return argsEditor || process.env.EDITOR || process.env.VISUAL || undefined
+	// needed for the process.env statements to not be flagged by eslint
+	// priority for editors is CLI argument > env.EDITOR > env.VISUAL
+}
+
+export async function configToKeyVal(data: string) {
+	let final: Record<string, string> = {};
+	let splitData = data.split(/\r?\n/);
+	// split on newlines
+	let filtered = splitData.filter((value) => value[0] !== "#").filter((a) => a);
+	// the last filter removes empty elements left by the first. Not done on one line due to readability.
+	for (let index in filtered) {
+		if (index in filtered) {
+			let split = filtered[index].split("=");
+			let finalIndex = filtered[index][0].trim();
+			// split on the = we added earlier, giving us both value and key
+			let part = "";
+			try {
+				part = split[1].trim();
+				// it's a string if we can read it
+			} catch (err) {
+				// if we can't read it, it's a empty field and therefor null
+				part = "";
+			}
+			final[finalIndex] = part;
+		}
+	}
+	return final;
+}
+
+export function serializedConfigToString(
+	serializedConfig: lib.ConfigSchema,
+	configGroup: typeof lib.ControllerConfig | typeof lib.HostConfig | typeof lib.InstanceConfig,
+	disallowedList: Record<string, unknown>,
+) {
+	let allConfigElements = "";
+	for (let [name, value] of Object.entries(serializedConfig)) {
+		if (name in disallowedList) {
+			continue;
+		}
+		let desc = "";
+		try {
+			desc += (configGroup.fieldDefinitions as any)[name]!.description;
+		} catch (err) {
+			desc += "No description found";
+		}
+		// split onto two lines for readability and es-lint
+		if (String(value) === "null") {
+			value = "";
+		}
+		allConfigElements += `${name} = ${value}\n\n`;
+	}
+	return allConfigElements;
+}
@@ -4,7 +4,4 @@
 		{ "path": "../lib/tsconfig.node.json" },
 	],
 	"include": ["index.ts", "package.json", "ctl.ts", "src/**/*.ts"],
-	"compilerOptions": {
-		"outDir": "dist/node",
-	},
 }