Land of OZ - Dedicated Server Manager - Valheim

About

TL;DR: A terminal-based Valheim server manager that doesn't need Docker, VMs, or a PhD in sysadmin.

This is a dedicated server manager for Valheim that runs directly on your machine—no containers, no virtualization, just TypeScript and Node.js. Born from the "Land of Oz" series of server management tools, this project aims to make hosting a Valheim server as painless as possible.

Whether you're running a private server for friends or managing a public realm, this tool handles the boring stuff (SteamCMD updates, crash recovery, config management) so you can focus on the Viking stuff (building, exploring, dying to Deathsquitos).

CONTRIBUTING.md if you want to help make it better.

Details

• Runtime: Node.js 22.x with TypeScript
• TUI Framework: Ink 6.x—React, but for your terminal
• Layout Engine: Yoga flexbox—the same layout engine that powers React Native
• Animations: ASCII Motion—why settle for static ASCII art when you can have animated ASCII art?
• State Management: Zustand

Quick Start

Installation

# Clone the repository
git clone https://github.com/caleb-collar/land-of-oz-dsm-valheim.git
cd land-of-oz-dsm-valheim

# Install dependencies
npm install

# Build the project
npm run build

# Run the TUI (recommended)
npm start

# Or use CLI commands directly
npm start -- --help

Ubuntu/Debian Prerequisites

SteamCMD requires 32-bit libraries on Ubuntu/Debian systems:

# Ubuntu/Debian (64-bit)
sudo dpkg --add-architecture i386
sudo apt update
sudo apt install lib32gcc-s1 lib32stdc++6 libc6:i386 libcurl4:i386

# Or use the all-in-one package
sudo apt install steamcmd

After installing prerequisites, run npm start -- install to set up SteamCMD and Valheim server.

Common Usage Examples

# Launch the interactive TUI (builds first)
npm start

# Or run the TUI directly after building
npm run build && node dist/main.js

# For development with live reload
npm run dev

# Install SteamCMD and Valheim server
npm start -- install

# Check your setup for issues
npm start -- doctor

# Start the server
npm start -- start --name "My Viking Server" --world "MyWorld"

# Start in background mode
npm start -- start --background

# Stop the server gracefully
npm start -- stop

# Force stop if unresponsive
npm start -- stop --force

# View/edit configuration
npm start -- config list
npm start -- config set server.port 2457
npm start -- config get server.name

# Manage worlds
npm start -- worlds list
npm start -- worlds info MyWorld
npm start -- worlds export MyWorld --path ./backup

# Send RCON commands (requires BepInEx mod)
npm start -- rcon save
npm start -- rcon "kick PlayerName"
npm start -- rcon --interactive

Note: On Node.js v23+, we use the built version instead of tsx for better compatibility. Use npm run dev for development with live reload.

TUI Keyboard Shortcuts

| Key | Action | | --------- | -------------------- | | 1 | Dashboard | | 2 | Settings | | 3 | Worlds | | 4 | Console | | 5 | Plugins | | ? | Show help overlay | | S | Start server | | X | Stop server | | M | Manage Admins | | Q | Quit application | | Ctrl+C | Force quit | | Esc | Close modal |

Features

Key features are as follows, all features have configuration available in the TUI:

• Windows, Mac, and Linux, task generation.
  • You may use the CLI with flags or CLI TUI to generate a task that auto runs with various options to keep the dedicated server running.
• Rich TUI based server setting configuration.
  • All of Valheim's dedicated server settings are accessible in properly ordered and organized in modern menus and sub menus.
• Automatic dependency installation if you opt in (will auto check and install steamcmd etc when run if you opt for this)
• Uses steamcmd to install and auto update Valheim when there are updates.
• Allows runtime server/admin commands to be run from the TUI.
• Watchdog to ensure that if the server crashes, it is auto restarted.
• Import existing save files (.db, .fwl pairs) and run them.
• Persistent configuration (settings, active world, etc persist between server and system restarts)

BepInEx Plugin Management

The DSM includes built-in support for BepInEx, the Unity modding framework. This enables server-side plugins that don't require clients to install anything.

Supported Plugins:

| Plugin | Author | Description | |--------|--------|-------------| | BepInEx.rcon | AviiNL | RCON protocol library for remote server management | | Server DevCommands | JereKuusela | Enhanced admin commands (kick, ban, events, time control) |

Plugin Features (press 5 for Plugins screen):

• Install/uninstall BepInEx framework
• Enable/disable individual plugins
• Configure plugin settings (RCON port, password)
• RCON features auto-activate when plugins are installed
• Admin role management (promote/demote players, manage root users)

Note: All supported plugins are server-side only — players connect with vanilla Valheim clients.

TUI

This TUI (Text User Interface) for Valheim DSM: Land of Oz is designed for high-efficiency server administration with a modern, animated "cyber-viking" aesthetic. It prioritizes real-time observability while keeping management tools front and center. Below is a generalized mockup of the DSM TUI built using React via Ink. Motion is created using ASCII Motion.

The Valheim DSM interface utilizes a structured three-zone TUI architecture designed for maximum administrative visibility. A bold animated ASCII header anchors the top of the screen, followed by a responsive layout that separates active management from passive monitoring. Where possible, the system uses Ink to display data (realtime active react components). There is a real-time log feed with color-coded event markers.

Architecture

Technology Stack

| Layer | Technology | Purpose | | ---------------- | ---------------- | ------------------------------------------------ | | Runtime | Node.js 22.x | TypeScript-first with tsx execution | | TUI Framework | Ink 6.x | React-based terminal UI with Yoga flexbox layout | | UI Library | React 19.x | Component-based rendering to terminal | | State Management | Zustand 5.x | Lightweight, React-compatible global state | | Animation | ASCII Motion MCP | Animated ASCII art for headers and transitions | | Process Control | child_process | Cross-platform subprocess management | | Configuration | conf 13.x | Persistent settings with JSON storage |

Directory Structure

land-of-oz-dsm-valheim/
├── package.json              # Node.js dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── vitest.config.ts          # Test configuration
├── biome.json                # Linting and formatting
├── main.ts                   # CLI entry point and argument parser
├── README.md                 # Project documentation (this file)
├── AGENTS.md                 # AI agent implementation guidance
├── .agent-docs/              # Detailed implementation references for agents
│   ├── 00-overview.md
│   ├── 01-tui-architecture.md
│   ├── 02-process-management.md
│   ├── 03-steamcmd-integration.md
│   ├── 04-configuration.md
│   └── 05-valheim-settings.md
│
├── src/
│   ├── mod.ts                # Public API exports
│   │
│   ├── bepinex/
│   │   ├── mod.ts            # BepInEx module exports
│   │   ├── types.ts          # Plugin types and definitions
│   │   ├── paths.ts          # BepInEx path detection
│   │   ├── installer.ts      # BepInEx download and install
│   │   └── plugins.ts        # Plugin management (install/enable/disable)
│   │
│   ├── cli/
│   │   ├── mod.ts            # CLI module exports
│   │   ├── args.ts           # Argument parsing (Cliffy or custom)
│   │   └── commands/         # Subcommand handlers
│   │       ├── start.ts
│   │       ├── stop.ts
│   │       ├── install.ts
│   │       └── config.ts
│   │
│   ├── tui/
│   │   ├── mod.ts            # TUI module exports
│   │   ├── App.tsx           # Root Ink component
│   │   ├── store.ts          # Zustand state store
│   │   ├── hooks/            # Custom React hooks
│   │   │   ├── useServer.ts
│   │   │   ├── useLogs.ts
│   │   │   ├── useConfig.ts
│   │   │   ├── usePlugins.ts       # BepInEx plugin management
│   │   │   ├── useRconAvailable.ts  # RCON feature gating
│   │   │   └── useAdminManager.ts   # Admin role management
│   │   ├── components/       # Reusable UI components
│   │   │   ├── Header.tsx          # Animated ASCII header
│   │   │   ├── StatusBar.tsx       # Server status indicators
│   │   │   ├── LogFeed.tsx         # Real-time color-coded logs
│   │   │   ├── Menu.tsx            # Navigation menu
│   │   │   ├── Modal.tsx           # Overlay dialogs
│   │   │   ├── AdminManager.tsx    # Admin/root user management
│   │   │   ├── PlayerManager.tsx   # Player kick/ban controls
│   │   │   ├── EventManager.tsx    # Event triggering
│   │   │   ├── TimeControl.tsx     # Time skip controls
│   │   │   ├── GlobalKeysManager.tsx # Boss progression
│   │   │   └── PluginItem.tsx      # Plugin list item
│   │   └── screens/          # Full-screen views
│   │       ├── Dashboard.tsx
│   │       ├── Settings.tsx
│   │       ├── Worlds.tsx
│   │       ├── Console.tsx
│   │       └── Plugins.tsx         # BepInEx plugin management
│   │
│   ├── server/
│   │   ├── mod.ts            # Server management exports
│   │   ├── process.ts        # Valheim process wrapper
│   │   ├── pidfile.ts        # PID file management for detached servers
│   │   ├── logTail.ts        # Log file tailing for detached mode
│   │   ├── watchdog.ts       # Crash detection and auto-restart
│   │   ├── logs.ts           # Log parsing and streaming
│   │   └── commands.ts       # Runtime admin command execution
│   │
│   ├── rcon/
│   │   ├── mod.ts            # RCON module exports
│   │   ├── types.ts          # RCON types and configuration
│   │   ├── protocol.ts       # Source RCON packet encode/decode
│   │   ├── client.ts         # TCP RCON client
│   │   ├── constants.ts      # Valheim RCON constants
│   │   └── manager.ts        # RCON manager with auto-reconnect
│   │
│   ├── steamcmd/
│   │   ├── mod.ts            # SteamCMD module exports
│   │   ├── installer.ts      # Auto-install SteamCMD
│   │   ├── updater.ts        # Valheim installation/updates
│   │   └── paths.ts          # Platform-specific path resolution
│   │
│   ├── config/
│   │   ├── mod.ts            # Configuration module exports
│   │   ├── schema.ts         # Zod schemas for validation
│   │   ├── store.ts          # conf package persistence layer (JSON)
│   │   └── defaults.ts       # Default configuration values
│   │
│   ├── valheim/
│   │   ├── mod.ts            # Valheim-specific exports
│   │   ├── settings.ts       # Server settings types and handlers
│   │   ├── worlds.ts         # World file management (.db, .fwl)
│   │   ├── args.ts           # Valheim CLI argument builder
│   │   └── admins.ts         # Admin/root user role management
│   │
│   └── utils/
│       ├── mod.ts            # Utility exports
│       ├── platform.ts       # OS detection and paths
│       ├── logger.ts         # Structured logging
│       └── events.ts         # Event emitter for internal messaging
│
└── assets/
    └── ascii/                # ASCII art assets (exported from ASCII Motion)
        ├── header.json
        └── spinner.json

Core Modules

1. CLI (src/cli/)

The command-line interface provides direct access to all DSM functionality:

• valheim-dsm start - Start the server (with optional --tui flag)
• valheim-dsm stop - Gracefully stop the server
• valheim-dsm install - Install/update Valheim via SteamCMD
• valheim-dsm config - View/edit configuration
• valheim-dsm tui - Launch the full TUI experience

2. TUI (src/tui/)

The terminal user interface is built with Ink (React for terminals):

• Three-Zone Layout: Header, Main Content, Log Feed
• Zustand Store: Centralized state for server status, settings, logs
• Component Library: Reusable, themed components with cyan/orange/green palette
• Keyboard Navigation: Full keyboard control with vim-style bindings

3. Server Process Management (src/server/)

Manages the Valheim dedicated server lifecycle:

• Process Wrapper: Spawn, monitor, and terminate the server process
• Watchdog: Detect crashes via exit codes and auto-restart with backoff
• Log Streaming: Parse stdout/stderr, categorize events, emit to TUI
• Command Injection: Send admin commands to the running server

4. SteamCMD Integration (src/steamcmd/)

Handles all Steam-related operations:

• Auto-Install: Download and configure SteamCMD per platform
• Update Detection: Check for Valheim updates before launching
• Anonymous Login: Valheim dedicated server doesn't require authentication

5. Configuration (src/config/)

Persistent settings management:

• conf Package: Cross-platform JSON-based configuration storage
• Zod Validation: Type-safe schema enforcement with runtime validation
• Migration Support: Handle config version upgrades gracefully

6. Valheim Integration (src/valheim/)

Game-specific functionality:

• Settings Types: Typed definitions for all server arguments
• World Management: Import, export, and switch between worlds
• Argument Builder: Construct valid Valheim CLI arguments

State Flow

graph TB
    subgraph "User Interaction Layer"
        TUI["TUI Components (Ink/React)"]
        CLI["CLI Commands"]
    end

    subgraph "State Management (Zustand)"
        Store["Global Store"]
        ServerState["server: {status, pid, players}"]
        ConfigState["config: {settings, world}"]
        LogState["logs: {entries, filter}"]
        UIState["ui: {activeScreen, modal}"]
        Store --> ServerState
        Store --> ConfigState
        Store --> LogState
        Store --> UIState
    end

    subgraph "Process Management"
        PM["Server Process Manager"]
        WD["Watchdog (Auto-restart)"]
        LS["Log Stream Parser"]
        PM --> WD
        PM --> LS
    end

    subgraph "Persistence Layer"
        Conf["conf (JSON Storage)"]
        Worlds["World Files (.db/.fwl)"]
    end

    subgraph "External Systems"
        Steam["SteamCMD"]
        Valheim["Valheim Server Process"]
        RCON["RCON Client (Optional)"]
    end

    TUI -->|User Input| Store
    CLI -->|Commands| Store
    
    Store -->|Read/Write| Conf
    Store -->|Start/Stop| PM
    Store -->|Send Commands| RCON
    
    PM -->|Spawn| Valheim
    PM -->|stdout/stderr| LS
    LS -->|Parsed Logs| LogState
    
    Valheim -->|Events| WD
    WD -->|Restart on Crash| PM
    
    ConfigState -->|Load| Conf
    Conf -->|Load Worlds| Worlds
    
    CLI -->|Install/Update| Steam
    Steam -->|Download| Valheim
    
    Store -->|React Updates| TUI
    RCON -.->|Commands| Valheim

    classDef userLayer fill:#F37A47,stroke:#B63C21,color:#fff
    classDef stateLayer fill:#018DA6,stroke:#01657C,color:#fff
    classDef processLayer fill:#FCF983,stroke:#000,color:#000
    classDef persistLayer fill:#691E11,stroke:#B63C21,color:#fff
    classDef externalLayer fill:#001018,stroke:#01657C,color:#fff
    
    class TUI,CLI userLayer
    class Store,ServerState,ConfigState,LogState,UIState stateLayer
    class PM,WD,LS processLayer
    class Conf,Worlds persistLayer
    class Steam,Valheim,RCON externalLayer

Valheim Server Settings

The DSM exposes all Valheim dedicated server settings through the TUI:

| Setting | Type | Description | | -------------- | ------- | ----------------------------- | | name | string | Server name shown in browser | | port | number | Server port (default: 2456) | | world | string | World name to load | | password | string | Server password (min 5 chars) | | savedir | path | Custom save directory | | public | boolean | List on public server browser | | logFile | path | Log file output path | | saveinterval | number | Save interval in seconds | | backups | number | Number of backup saves | | backupshort | number | Short backup interval | | backuplong | number | Long backup interval | | crossplay | boolean | Enable crossplay support | | preset | enum | Difficulty preset | | modifiers | object | Combat, death penalty, etc. |

Platform Support

| Platform | SteamCMD Path | Valheim Install | Config Storage | Notes | | ------------- | ---------------------------------------- | ------------------------------------------- | ------------------------------------------- | ----- | | Windows | %LOCALAPPDATA%\steamcmd | steamapps\common\Valheim dedicated server | %APPDATA%\oz-valheim | Fully supported | | macOS | ~/Library/Application Support/steamcmd | steamapps/common/Valheim dedicated server | ~/Library/Application Support/oz-valheim | Fully supported | | Linux (Ubuntu)| ~/.local/share/steamcmd | steamapps/common/Valheim dedicated server | ~/.config/oz-valheim | Requires 32-bit libs (see Installation) | | Linux (Other) | ~/.local/share/steamcmd | steamapps/common/Valheim dedicated server | ~/.config/oz-valheim | Fully supported |

Development

# Install dependencies
npm install

# Run in development mode (with live reload)
npm run dev

# Run tests
npm test

# Type check
npm run typecheck

# Lint and format
npm run lint
npm run format

# Build bundle
npm run build

# Run built version
node dist/main.js --help

# Or use npm start (builds automatically)
npm start -- --help

Note: The project uses Biome for linting and formatting.

Node.js Requirements

• Node.js 22.x or later
• npm 10.x or later

Troubleshooting

Run npm start -- doctor to automatically diagnose common issues.

Common Issues

SteamCMD not found

Error: SteamCMD not found

Solution: Run npm start -- install to automatically download and install SteamCMD.

Ubuntu/Debian: If you get library errors, install 32-bit dependencies first:

sudo dpkg --add-architecture i386
sudo apt update
sudo apt install lib32gcc-s1 lib32stdc++6 libc6:i386 libcurl4:i386

SteamCMD installation crashes with "Cannot read properties of undefined (reading 'x')"

This was caused by a TypeScript/CommonJS interop bug in @caleb-collar/[email protected]. The package incorrectly tries to access tar.default.x, but the tar v7 package doesn't export a default (it exports the API directly).

Solution (Fixed in v1.5.3):

1. Update to v1.5.3 or later
2. Run npm install - this will automatically apply the patch that fixes the tar import
3. The patch changes tar_1.default.x to tar_1.x in the steamcmd package
4. Patches are stored in patches/@caleb-collar+steamcmd+1.1.0.patch and auto-applied via patch-package

Manual fix (if needed):

rm -rf node_modules package-lock.json
npm install

Valheim server not starting

Possible causes:

1. Port already in use - Valheim requires ports 2456-2458. Check if another process is using them:

   # Windows
   netstat -ano | findstr :2456
      
   # Linux/macOS
   lsof -i :2456

2. Insufficient permissions - Run as administrator/root on first launch.

3. SteamCMD needs update - Run npx tsx main.ts install --force to reinstall.

Configuration errors

Error: Failed to load configuration

Solution: Reset configuration to defaults:

npx tsx main.ts config reset

Terminal display issues

If the TUI appears corrupted or doesn't render correctly:

1. Try a different terminal - Windows Terminal, PowerShell, or iTerm2 work best
2. Check terminal size - Minimum 80x24 recommended
3. Disable Unicode fallback - Some terminals need UTF-8 encoding enabled

RCON connection failed

Error: RCON connection refused

Possible causes:

1. RCON requires the BepInEx mod pack with RCON plugin installed on the server
2. Check RCON port and password match your server configuration:

   npx tsx main.ts config set rcon.port 25575
   npx tsx main.ts config set rcon.password "yourpassword"

Server crashes immediately

Check the Valheim log file for details:

• Windows: %USERPROFILE%\AppData\LocalLow\IronGate\Valheim\
• Linux: ~/.config/unity3d/IronGate/Valheim/

Common causes:

• Invalid world name (use alphanumeric characters only)
• Password too short (minimum 5 characters)
• Corrupted world files

Getting Help

1. Run diagnostics: npx tsx main.ts doctor
2. Check logs in the TUI Console screen (press 4)
3. Review Valheim server logs in the save directory
4. Open an issue on GitHub with:
   • Output of npx tsx main.ts doctor --json
   • Relevant error messages
   • Your platform and Node.js version

Repo details

This repo is open source and free to use