CurseForge Mods

Automatically download and sync mods from CurseForge on every container startup.

Setup

Get a CurseForge API Key

Go to CurseForge for Studios
Create an account or log in
Create a new API key
Copy the key

Configure Environment

Add to your docker-compose.yml:

environment:
  CF_API_KEY: "${CF_API_KEY}"  # From .env file (escape $ as $$ if you inline the key)
  CF_MODS: "123456,789012"

Create a .env file:

CF_API_KEY=your-api-key-here

If you paste the API key directly in docker-compose.yml, escape any $ characters as $$ or you may get 403 errors in the logs.

Find Project IDs

The project ID is in the CurseForge mod URL or on the mod page under "Project ID":

https://www.curseforge.com/hytale/mods/example-mod

Restart

docker compose restart

Configuration

CF_MODS Format

CF_MODS: "projectId,projectId:fileId,projectId"

Format	Description
`123456`	Latest version
`123456:789`	Specific file ID

Example

environment:
  CF_API_KEY: "${CF_API_KEY}"
  CF_MODS: "123456,789012:456,654321"

Release Type Filtering

Mod versions are automatically filtered based on your PATCHLINE setting:

PATCHLINE	Mods downloaded
`release` (default)	Only stable releases
`pre-release`	All versions (stable, beta, alpha)

This prevents unstable mod versions from being installed on a release server. For example, if a mod like BetterMap publishes both stable and pre-release versions, only the latest stable version will be downloaded when PATCHLINE=release.

To bypass filtering for a specific mod, pin it to an exact file ID: CF_MODS: "123456:789". Pinned versions ignore the release type filter.

How It Works

On every startup:

Parse CF_MODS configuration
Filter available versions by release type (based on PATCHLINE)
Check each mod version
Download new or updated mods
Remove mods no longer in CF_MODS
Update manifest at /server/mods/.curseforge-manifest.json

CLI Commands

# List installed mods
docker exec -it hytale-server hytale mods list

# Force update a mod
docker exec -it hytale-server hytale mods update 123456

List Output

Installed CurseForge Mods:
──────────────────────────────────────────────────
  123456:789 → ExampleMod-1.2.3.jar
  654321:456 → AnotherMod-2.0.0.jar

Startup Log

[INFO] Syncing 3 CurseForge mod(s)
[INFO]   ✓ ExampleMod (up to date)
[INFO]   ↓ NewMod (NewMod-1.0.0.jar)
[INFO]   ✗ Removing OldMod-0.9.0.jar
[SUCCESS] CurseForge mods synced (3 mods)

Complete Example

services:
  hytale:
    image: rxmarin/hytale-docker:latest
    container_name: hytale-server
    restart: unless-stopped
    stdin_open: true
    tty: true
    ports:
      - "5520:5520/udp"
    environment:
      JAVA_OPTS: "-Xms4G -Xmx8G"
      AUTO_UPDATE: "true"
      CF_API_KEY: "${CF_API_KEY}"
      CF_MODS: "123456,789012"
    volumes:
      - hytale-data:/server

volumes:
  hytale-data:

Always use a .env file for your API key instead of committing it to version control.

Troubleshooting

Issue	Solution
"CF_API_KEY not set"	Add `CF_API_KEY` to environment or `.env` file
"Mod not found"	Verify the project ID is correct
"Download failed"	Check if mod allows API downloads on CurseForge
Mod not loading	Check server logs and mod compatibility

Verify Installation

docker exec hytale-server ls /server/mods/

Removing Mods

Remove the project ID from CF_MODS and restart:

# Before
CF_MODS: "123456,789012,456789"

# After (removed 789012)
CF_MODS: "123456,456789"

docker compose restart

The mod file is automatically deleted on startup.

Next Steps

CLI Reference — Full CLI documentation
Configuration — All environment variables

CurseForge Mods

On this page