# Install plugins, mods and modpacks

> Search the marketplace for plugins, mods, datapacks and modpacks, check their dependencies and install them.

Source: https://docs.coritan.com/managed-containers/software/plugins-and-mods/

In the dashboard:

- /dashboard/servers/…/software: https://www.coritan.com/dashboard/servers

The **Marketplace** panel on a server's **Software** tab searches the addon sources we connect to, such as Modrinth, and installs what you choose onto the server. Each install runs as a job that you can follow, cancel and retry. We keep a record of everything the Marketplace installs, so you can update or remove it later on the [Installed addons](/managed-containers/software/installed-addons/) panel.

## Before you begin

- The server must be installed.
- Take a [snapshot](/managed-containers/snapshots/) before you install a modpack. A modpack stops the server, adds its files on top of yours and can switch the server to other software.
- On a server someone shared with you, the Install software permission lets you search and install. Removing an install needs `software.delete`, which the dashboard's permission list does not offer, so the owner can grant it only [through the API](/managed-containers/users/#with-the-api).

What you can search for depends on the server's software:

| Software | What the Marketplace offers |
| --- | --- |
| Plugin servers, such as Paper, Purpur and Spigot | Plugins, modpacks, datapacks and resource packs |
| Mod loaders: Fabric, Quilt, Forge and NeoForge | Mods, modpacks, datapacks and resource packs |
| Arclight, Mohist and Magma, which load both | Plugins, mods, modpacks, datapacks and resource packs |
| Vanilla | Modpacks, datapacks and resource packs |
| Velocity and BungeeCord | Plugins. NanoLimbo loads no addons. |
| Bedrock Dedicated Server | Bedrock add-ons and resource packs, which [Manage Bedrock packs](/managed-containers/software/bedrock-packs/) covers |

## Find an addon

1. In the [dashboard](https://www.coritan.com/dashboard/servers), go to **Container Apps** and open the server, then the **Software** tab.
2. Select **Marketplace**.
3. In the list before the search field, choose what to look for: **Plugins**, **Mods**, **Datapacks** or **Modpacks**.
4. Type a name in the search field, such as `LuckPerms`, and select **Search**.

Each result shows the addon's name, its kind, a short description, the source it comes from, its author and how many times it has been downloaded.

For plugins, mods, datapacks and resource packs, the results list only projects with a build for your server's software and Minecraft version. A Paper server also finds plugins published for Spigot and Bukkit, and a Quilt server finds Fabric mods. Modpack results are not narrowed, because a modpack brings its own loader and Minecraft version.

## Install an addon

1. Find the addon, then select **Install…** on its result.
2. Choose a build in **Version**. A build the source does not let us download shows `(not installable)` and cannot be chosen.
3. To see what the build needs, select **Dependencies**. [Check dependencies](#check-dependencies) explains the list.
4. Select **Install**.

> [!NOTE]
> The **Version** list shows the builds the source publishes for every loader and Minecraft version, and it selects the first one. Check that the build you choose names your server's software and Minecraft version. The install job refuses a build made for anything else.

A message confirms that the install is queued, and the job appears in the jobs card at the top of the **Software** tab. **Project page** opens the addon's page on its source, where you can read its instructions.

The file goes into the folder the server loads that kind of addon from:

| Kind | Folder |
| --- | --- |
| Plugin | `plugins` |
| Mod | `mods` |
| Datapack | The world's `datapacks` folder, such as `world/datapacks`. It follows `level-name` in `server.properties`. |

The install does not stop or restart the server. Restart it from the [console](/managed-containers/console/) to load the new addon.

Plugin, mod and datapack installs can run side by side. A modpack, a software change or anything that deletes files waits for earlier jobs to finish and then runs alone. While a job waits, it shows `Waiting`, and the panel says `Another software job is running; this one queues behind it.`

## Check dependencies

Select **Dependencies** next to **Install** to list the projects the chosen build names. Each row has a badge:

`Required`
: The addon does not work without it.

`Optional`
: The addon works without it and uses it when it is there.

`Incompatible`
: The addon does not work alongside it.

Next to each row, the state says `Installed`, `Installing` or `Not installed`. An incompatible project that is not on the server shows `Conflicts`. When an incompatible project shows `Installed`, remove it or choose another addon.

`No dependencies: it runs on its own.` means the build names none.

> [!WARNING]
> When required dependencies are missing, the panel says the installer adds them with the addon, such as `2 required dependencies are not installed yet; the installer adds them with this one.` The dashboard installs only the addon you chose. Install each required dependency yourself from the Marketplace, or send them in `dependencies` [through the API](#with-the-api), which installs them for you.

A required dependency that only runs in players' games is left out of that count, because the server does not need it.

## Install a modpack

1. On the **Marketplace** panel, choose **Modpacks** and search for the pack.
2. Select **Install…** and choose a version. A note names the loader and Minecraft version the pack runs on, such as `This pack runs on Fabric 1.21.1.`, and says whether we switch the server to them.
3. Select **Install**.

The install then runs in this order:

1. The job stops the server.
2. It downloads the pack and adds the pack's server files beside the files already on the server. It merges the pack's `overrides` folder into the server's folders. It skips folders that only players' games read, such as `resourcepacks` and `shaderpacks`, and mods whose publisher says they only run in the game.
3. When the server does not already run the pack's loader and Minecraft version, a software change to them follows as a second job. It keeps your files and sets the server up to run the new loader, as [Change the server software](/managed-containers/software/) describes.

Neither job starts the server. Start it from the [console](/managed-containers/console/) when both jobs show `Succeeded`.

> [!WARNING]
> Minecraft cannot load a world saved by a newer version. When the pack runs an older Minecraft version than your world was last saved with, the world does not load after the switch. The note on the panel warns you when the versions differ.

The dashboard adds the pack on top of what is there, so mods from before stay in `mods` and can clash with the pack's. To start from an empty server, delete the old files in the [Files tab](/managed-containers/files/) first, or install through the API with `mode` set to `replace`, which deletes every file on the server before the install.

We do not track the mods in a pack one by one. They show as **Uploaded by hand** on the **Installed addons** panel, and we cannot check them for updates. The pack itself is listed under **Installed from the marketplace**, but it cannot be removed there: to move to another pack, install it through the API with `mode` set to `replace`.

## Resource packs and server software

The kind list also offers **Resource packs**, but the Marketplace cannot install one. Players' games download a server resource pack from a link, so nothing goes onto the server. Set it on the [Resource pack](/managed-containers/software/resource-pack/) panel with the pack's download link instead.

On some servers the list offers `server_jar` too. Change the server's own software under [Server software](/managed-containers/software/) instead, so the Java runtime and startup command change with it.

## Remove an install

Everything the Marketplace installed is listed under **Installed from the marketplace**, below the search, with its version, kind, source, path and install date.

1. Select the bin icon at the end of the row.
2. Confirm in the dialog.

We delete the files that install wrote and drop our record of it, straight away. The server keeps a removed plugin or mod loaded until it restarts. The addon's data folder, such as `plugins/LuckPerms`, stays: delete it in the [Files tab](/managed-containers/files/) if you no longer need its settings.

The [Installed addons](/managed-containers/software/installed-addons/) panel removes addons too, and it also lists the files you uploaded yourself.

## Result

The job shows `Queued`, then `Running` with stages such as `Resolving`, `Downloading` and `Finalizing`, then `Succeeded`. The addon is in its folder, and it is listed under **Installed from the marketplace** and on the **Installed addons** panel. It loads the next time the server starts.

A modpack's job also shows `Stopping` and `Extracting`, and a software change job may follow it.

## Troubleshooting

The addon does not load after a restart
: Open **Dependencies** for its version and install every `Required` project that shows `Not installed`. The [console](/managed-containers/console/) shows the error the server hit while loading it.

`No version of this is compatible with the server.`
: The source lists no builds for this project, or we could not reach the source. Try again later, or choose another addon.

`Minecraft Paper loads plugins, datapacks and a server resource pack, not mods.`
: The server's software cannot load that kind of addon. The message names your software and what it loads. Choose another kind, or [change the software](/managed-containers/software/).

`This build was published for a different mod loader than this server runs.`
: The job failed because the build you chose is for other software. The message starts with the build's name and what your server runs. Install again and choose a build made for your server's software.

`This build was not published for this server's Minecraft version.`
: The build is for another Minecraft version. Install again and choose a build for your server's version.

`This is a client-side mod. It runs in each player's game, not on the server, and on a server it does nothing or stops it from starting.`
: The publisher says the project only runs in players' games. We never install it on a server. Players install it in their own game.

`SpigotMC only allows the newest release to be downloaded automatically. Install the latest version, or upload the jar yourself in Files.`
: The plugin comes from SpigotMC, which shows as the `Spiget` source. Install the newest version, or download the version you want and upload it in the [Files tab](/managed-containers/files/).

`This is a paid SpigotMC resource. Buy it on SpigotMC, then upload the jar in Files.`
: We cannot download paid plugins for you. Upload the jar yourself.

`This resource is hosted off-site. Open the project page, download the jar, then upload it in Files.`
: The publisher hosts the file somewhere we cannot download from. Upload the jar yourself.

`This release has no downloadable file attached.`
: The publisher uploaded no file for that build. Choose another version.

`That version no longer exists on the source.`
: The publisher removed the build. Choose another version.

`This source is temporarily unavailable. Try again shortly.`
: The source did not answer. Select **Try again** on the job later.

`The download did not finish in time. Try again.`
: Select **Try again** on the job.

`This modpack does not publish a server pack, so it cannot be installed on a server automatically. Look for a version with a server pack, or set it up by hand in Files.`
: A CurseForge modpack installs only from a version that publishes a server pack. Choose another version, or another pack.

`The author has not allowed this file to be installed by third parties. Download it from CurseForge and upload it in Files.`
: Download the file from CurseForge and upload it in the [Files tab](/managed-containers/files/).

`A server resource pack is not downloaded onto the server; players fetch it from a URL. Apply it with the resource pack tool instead.`
: Resource packs are set with a link. Use the [Resource pack](/managed-containers/software/resource-pack/) panel.

`Modpacks cannot be uninstalled file-by-file; install another modpack with mode=replace instead`
: A modpack's files mix with yours, so we cannot tell which ones to delete. Install another pack through the API with `mode` set to `replace`, or delete the files in the [Files tab](/managed-containers/files/).

`Cannot uninstall while a replace, wipe, or software change is in progress. Wait for it to finish or cancel it first.`
: A job that replaces the server's files is running. Wait for it, or select **Cancel job** on it, then remove the addon.

`Too many requests for this action. Please wait and try again.`
: A server accepts 8 software actions from one account in 10 minutes, and each install counts. Searching does not. The response says how many seconds to wait.

## Related

- [Manage installed addons](/managed-containers/software/installed-addons/)
- [Install server updates](/managed-containers/updates/)
- [Set a server resource pack](/managed-containers/software/resource-pack/)
- [Change the server software](/managed-containers/software/)
- [Manage files](/managed-containers/files/)

## With the API

The paths below are relative to `/api/v1/client/servers/{uuid}`.

`GET /software/sources` lists the sources you can search. Add `?kind=plugin`, or another kind, for the sources that carry it. Each source has a `uuid`, `slug`, `name`, `adapter_type`, `supported_kinds`, `sort_options`, `supports_search` and `configured`.

### Search

```bash
curl -X POST https://api.coritan.com/api/v1/client/servers/$SERVER/software/search \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "luckperms", "kind": "plugin"}'
```

| Field | What it does |
| --- | --- |
| `query` | The name to search for. |
| `kind` | `plugin`, `mod`, `modpack`, `datapack`, `resourcepack`, `server_jar`, `bedrock_addon` or `bedrock_resource_pack`. With a kind, the search fits the server's software and Minecraft version, as in the dashboard. |
| `page` | The page, from 1. |
| `limit` | Results per source and page, 1–100. The default is 20. |
| `source_uuid` | Search one source only. |
| `sort` | One of the source's `sort_options` values. |
| `loaders`, `game_versions` | Narrow the search further. You can narrow within what the server runs but not go outside it. |

```json
{
  "items": [
    {
      "identifier": "Vebnzrzj",
      "name": "LuckPerms",
      "kind": "plugin",
      "description": "A permissions plugin for Minecraft servers.",
      "downloads": 1520000,
      "project_url": "https://modrinth.com/plugin/luckperms",
      "source_uuid": "0f7c2a4e-5b1d-4c3a-9e8f-2d6b1a7c9e30",
      "source_name": "Modrinth",
      "adapter_type": "modrinth"
    }
  ],
  "errors": [],
  "page": 1,
  "limit": 20,
  "total": 1,
  "has_more": false,
  "scope": {
    "loader": "paper",
    "game_version": "1.21.4",
    "loaders": ["paper", "spigot", "bukkit", "purpur", "folia"],
    "game_versions": ["1.21.4"]
  }
}
```

A result also carries `slug`, `author`, `icon_url`, `loaders` and `game_versions`. `errors` names each source that failed, with its `source_name` and `message`, while the others still answer. `sources` counts the results from each source, and `scope` says what the search was narrowed to. A kind the server cannot load returns no results and the reason in `unsupported_kind`.

### Versions and dependencies

`GET /software/versions/{source_uuid}/{identifier}?kind=plugin` returns `versions`. With `kind` set to `plugin`, `mod`, `datapack` or `resourcepack`, the list holds only the builds that fit the server, and each row says so in `compatible`. Add `include_incompatible=true` to list every build, with `incompatible_reason` set to `incompatible_loader` or `incompatible_game_version` where it does not fit. Each row has a `version_id` to install, a `name`, `release_date`, `game_versions`, `loaders`, `version_type` and `installable`, with `reason_text` when a build cannot be installed. `page` and `limit` (1–200, default 50) page through the list.

`GET /software/dependencies/{source_uuid}/{identifier}?version=latest&kind=plugin` resolves a build's dependencies. Pass a `version_id` in `version`, or `latest` for the build an install would choose. The response has `dependencies` (required and optional), `incompatible`, `embedded` and `missing_required`. Each row has the project's `identifier`, `name`, `dependency_type`, `client_only`, `installed` and `installing`, and `record_uuid` and `installed_version` when it is on the server. `missing_required` lists the identifiers of required dependencies that are not installed, not installing and not client-side: send it as `dependencies` when you install.

### Install

```bash
curl -X POST https://api.coritan.com/api/v1/client/servers/$SERVER/software/install \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source_uuid": "0f7c2a4e-5b1d-4c3a-9e8f-2d6b1a7c9e30", "identifier": "Vebnzrzj", "kind": "plugin"}'
```

| Field | What it does |
| --- | --- |
| `source_uuid` | Required. The source, from the search results. |
| `identifier` | Required. The project, from the search results. |
| `kind` | Required. `plugin`, `mod`, `modpack`, `datapack`, `server_jar`, `bedrock_addon` or `bedrock_resource_pack`. |
| `version` | A `version_id`. The default, `latest`, installs the newest release that fits the server, or the newest build when the project publishes no releases. |
| `mode` | `add`, the default, installs beside what is there. `replace` deletes every file on the server first and needs `confirm_server_name`. `update` replaces the build of a project we already track. A modpack takes `add` or `replace`. |
| `confirm_server_name` | The server's name, to confirm `replace`. Case does not matter. |
| `stop_server` | `true` stops the server before the install. `replace` and modpacks always stop it. |
| `display_name` | The name the jobs list shows. |
| `dependencies` | Up to 25 identifiers from the same source to install with it, for plugins, mods and datapacks. Each gets its own job at the newest build that fits. We skip those already installed and those that only run in players' games. |
| `allow_incompatible` | `true` installs a build made for another loader or Minecraft version. Client-side mods are refused whatever you send. |

The response is the install job, with its `uuid`, `kind`, `mode`, `status`, `stage`, `progress` and `requested_version`. When you sent `dependencies`, `dependency_installs` lists their jobs. Follow a job with `GET /software/installs/{install_uuid}`, as [Change the server software](/managed-containers/software/#with-the-api) explains. Sending the same project while its install is queued or running returns that job instead of a new one.

`GET /software` lists every install we track on the server, newest first. Each record has a `uuid` to pass as `record_uuid`, with `source_uuid`, `identifier`, `kind`, `current_version`, `version_name`, `install_path`, `display_name`, `source_name` and `installed_at`.

`DELETE /software/{record_uuid}` deletes the files the install wrote and the record. It answers `{"deleted": true, "uuid": "…", "identifier": "…"}`, and it does not stop the server.

| Status | When |
| --- | --- |
| `400` | A field is missing or wrong, such as `source_uuid and identifier are required`, `kind is required (plugin, mod, modpack, datapack, server_jar, bedrock_addon or bedrock_resource_pack)`, `mode must be one of: add, replace, update` or `at most 25 dependencies can be installed at once`. A `replace` without the server's name answers `Type the server name to confirm deleting every file on the server`. The server's software cannot load the kind, or the kind is a resource pack. |
| `404` | The record does not exist: `Installed software not found`. |
| `409` | Removing a modpack, or removing while a job that replaces the server's files is running. |
| `429` | More than 8 software actions from your account on this server in 10 minutes. |

On a server shared with you, listing sources, versions, dependencies and installs needs `software.read`. Searching needs `software.search`, installing needs `software.install` and removing needs `software.delete`.

## API

- `GET /api/v1/client/servers/{uuid}/software/sources`: List enabled software sources for a kind (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-get-api-v1-client-servers-uuid-software-sources)
- `POST /api/v1/client/servers/{uuid}/software/search`: Search available software (JSON body preferred; query params kept for back-compat) (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-post-api-v1-client-servers-uuid-software-search)
- `GET /api/v1/client/servers/{uuid}/software/versions/{source_uuid}/{identifier}`: Get available versions for software (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-get-api-v1-client-servers-uuid-software-versions-source-uuid-identifier)
- `GET /api/v1/client/servers/{uuid}/software/dependencies/{source_uuid}/{identifier}`: What a version requires, named, with what is already installed marked (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-get-api-v1-client-servers-uuid-software-dependencies-source-uuid-identifier)
- `POST /api/v1/client/servers/{uuid}/software/install`: Queue a software install job (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-post-api-v1-client-servers-uuid-software-install)
- `GET /api/v1/client/servers/{uuid}/software`: List installed software records for a server (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-get-api-v1-client-servers-uuid-software)
- `DELETE /api/v1/client/servers/{uuid}/software/{record_uuid}`: Uninstall a tracked software artifact (https://docs.coritan.com/api/reference/client/container-apps/servers-software/#op-delete-api-v1-client-servers-uuid-software-record-uuid)