Dedicated Services

Dedicated services are a new first-class concept in Nimbus for servers that don't fit the "spawn N identical copies from a template" model. They sit alongside server groups and are meant for:

• Sandbox / test servers — throw-away experiments or dev environments
• Single-instance modpacks — one ATM10 server for your community, not a dynamic pool
• Custom servers — hand-curated configs, worlds, and plugins that should never be reset
• One-off side projects — a creative world, a mapping server, a survival side-build

Dedicated services trade scaling for simplicity. Everything is fixed: one instance, one port, one directory. Nimbus still manages the lifecycle (start, stop, auto-restart on crash, proxy registration), but it stops trying to be smart about templates.

How they differ from groups

Creating a dedicated service

From the dashboard

Open /dedicated in the dashboard, click New Dedicated, and fill in:

• Name — unique identifier, alphanumeric + dash + underscore
• Port — any free TCP port on the host
• Software — Paper, Purpur, Folia, Forge, NeoForge, Fabric, Custom, etc. (fetched from /api/software)
• Version — populated from /api/software/<name>/versions with the latest pre-selected
• Memory — -Xmx for the JVM (e.g. 2G, 4G)
• Proxy Enabled — whether this service should be registered with Velocity
• Restart on Crash — auto-restart on unexpected exit

The directory is auto-created at dedicated/<name>/, and the server JAR is downloaded on first start. No manual file management needed.

From the console

nimbus » dedicated create

The interactive wizard mirrors the dashboard create flow. Same inputs, same result.

From the REST API

POST /api/dedicated
Content-Type: application/json

{
  "name": "sandbox",
  "port": 25570,
  "software": "PAPER",
  "version": "1.21.4",
  "memory": "2G",
  "proxyEnabled": true,
  "restartOnCrash": true
}

Importing a modpack as a dedicated service

Modpack import works the same way as for groups — but the pack files land in the dedicated service directory instead of a template.

From the dashboard

Click Import Modpack on the /dedicated page. Choose between:

• Modrinth / CurseForge — paste a URL, slug, or curseforge:all-the-mods-10, click Resolve to see the modpack info (name, version, modloader, mod count), then click Import
• Upload Server Pack — drag & drop a .zip or .mrpack file

Nimbus auto-detects the modloader (Forge, NeoForge, Fabric) and MC version from the pack, installs the correct proxy forwarding mod (if proxyEnabled is on), writes eula.txt, and creates the dedicated service config in one step.

From the REST API

POST /api/dedicated/modpack/import
Content-Type: application/json

{
  "source": "all-the-mods-10",
  "name": "ATM10",
  "port": 25580,
  "memory": "8G",
  "proxyEnabled": true
}

Or for uploads:

POST /api/dedicated/modpack/upload?name=ATM10&port=25580&memory=8G&proxyEnabled=true&fileName=ServerFiles-6.6.zip
Content-Type: application/octet-stream

<raw ZIP body>

Proxy integration

Dedicated services have a proxyEnabled flag that controls whether they show up in Velocity's server list:

• proxy_enabled = true (default) — registered in velocity.toml, accessible via /server <name>, forwarding mods auto-installed for modded servers
• proxy_enabled = false — completely standalone. The server still runs under Nimbus, but players connect directly via the server address + port. Useful for standalone Velocity proxies, test servers that shouldn't appear on your network, or servers behind their own firewall rules

Toggling proxyEnabled in the edit dialog is applied immediately: for modded servers, the correct forwarding mod is installed (when enabled) or removed (when disabled), and the forwarding config is patched with the current Velocity secret. You still need to restart the service for the change to take effect at runtime.

Editing a dedicated service

Use the Edit action in the dashboard dropdown menu (or PUT /api/dedicated/{name}) to change:

• Port
• Memory
• Proxy enabled
• Restart on crash

Software and version are intentionally not editable — changing them would require re-downloading the server JAR and potentially cleaning up the directory. To switch software, delete the dedicated service and create a new one.

Directory layout

<nimbus-root>/
├── config/
│   └── dedicated/
│       ├── sandbox.toml
│       └── ATM10.toml
└── dedicated/
    ├── sandbox/
    │   ├── eula.txt
    │   ├── server.properties
    │   ├── paper-1.21.4.jar
    │   └── world/
    └── ATM10/
        ├── eula.txt
        ├── mods/
        ├── config/
        ├── libraries/
        └── neoforge-*.jar

Config TOML:

[dedicated]
name = "sandbox"
port = 25570
software = "PAPER"
version = "1.21.4"
memory = "2G"
proxy_enabled = true
restart_on_crash = true
max_restarts = 5

[dedicated.jvm]
args = []
optimize = true

Running dedicated services on cluster nodes

Dedicated services can be pinned to agent nodes via [dedicated.placement] with the same semantics as group placement:

[dedicated]
name = "sandbox"
port = 25570
software = "PAPER"
version = "1.21.4"
memory = "2G"

[dedicated.placement]
node = "worker-1"     # pin to this agent
fallback = "wait"     # wait for node if offline (recommended)

How it works: Remote placement for dedicated services always uses the state sync mechanism — the controller's dedicated/<name>/ directory is the canonical copy, and the agent pulls it on every start and pushes changes back on every graceful stop. This lets dedicated services float between nodes without losing their persistent data, as long as stops are graceful.

Data loss model: Same as group sync — graceful stop = zero loss; unplanned crash = loss since the last push. For zero-loss guarantees on dedicated services, keep them on the controller (omit [dedicated.placement] or set node = "local").

First start on a node: The dedicated directory must already exist on the controller (dedicated/<name>/) before remote placement. If the controller canonical is empty, the agent will refuse to start — dedicated services have no template fallback. Create the service locally first (it'll download the JAR, generate configs, etc.), then enable remote placement.

The paths.dedicated setting in nimbus.toml controls the base directory:

[paths]
templates = "templates"
services = "services"
dedicated = "dedicated"    # base dir for dedicated service working directories
logs = "logs"

Console commands

dedicated list                 — list all dedicated services
dedicated create               — interactive creation wizard
dedicated info <name>          — show config + runtime state
dedicated start <name>         — start the service
dedicated stop <name>          — stop the service
dedicated restart <name>       — restart
dedicated delete <name>        — delete the config (stops if running)

Tab-completion works for all subcommands and the <name> argument.

When to use groups vs dedicated

Use groups when you want:

• Multiple identical instances (minigames, lobbies, game servers)
• Auto-scaling based on player count
• Template-driven deployments (CI/CD-friendly)
• Consistent configuration across instances

Use dedicated services when you want:

• A single, persistent server you maintain manually
• A fixed port for external connections
• Experiments or sandboxes that don't need templates
• A standalone modpack server without the template overhead

Nothing stops you from mixing both — a typical setup is a Velocity group, a Lobby group, a few minigame groups, and a handful of dedicated services for creative worlds or test servers.