Land of OZ - Valheim Dedicated Server Manager
npm install valheim-oz-dsm

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.
- 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)[https://ascii-motion.app/]—why settle for static ASCII art when you can have animated ASCII art?
- State Management: Zustand
``bashClone the repository
git clone https://github.com/caleb-collar/land-of-oz-dsm-valheim.git
cd land-of-oz-dsm-valheim
#### Ubuntu/Debian Prerequisites
SteamCMD requires 32-bit libraries on Ubuntu/Debian systems:
`bash
Ubuntu/Debian (64-bit)
sudo dpkg --add-architecture i386
sudo apt update
sudo apt install lib32gcc-s1 lib32stdc++6 libc6:i386 libcurl4:i386Or use the all-in-one package
sudo apt install steamcmd
`After installing prerequisites, run
npm start -- install to set up SteamCMD and Valheim server.$3
`bash
Launch the interactive TUI (builds first)
npm startOr run the TUI directly after building
npm run build && node dist/main.jsFor development with live reload
npm run devInstall SteamCMD and Valheim server
npm start -- installCheck your setup for issues
npm start -- doctorStart the server
npm start -- start --name "My Viking Server" --world "MyWorld"Start in background mode
npm start -- start --backgroundStop the server gracefully
npm start -- stopForce stop if unresponsive
npm start -- stop --forceView/edit configuration
npm start -- config list
npm start -- config set server.port 2457
npm start -- config get server.nameManage worlds
npm start -- worlds list
npm start -- worlds info MyWorld
npm start -- worlds export MyWorld --path ./backupSend 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.$3
| Key | Action |
| --------- | -------------------- |
|
1 | Dashboard |
| 2 | Settings |
| 3 | Worlds |
| 4 | Console |
| ? | Show help overlay |
| S | Start server |
| X | Stop server |
| Q | Quit application |
| Ctrl+C | Force quit |
| Esc | Close modal |Features
$3
- 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)
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. !tui
---
Architecture
$3
| 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 |
$3
`
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
│ │
│ ├── 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
│ │ ├── 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
│ │ │ ├── SettingsPanel.tsx # Server settings editor
│ │ │ └── Modal.tsx # Overlay dialogs
│ │ └── screens/ # Full-screen views
│ │ ├── Dashboard.tsx
│ │ ├── Settings.tsx
│ │ ├── Worlds.tsx
│ │ └── Console.tsx
│ │
│ ├── server/
│ │ ├── mod.ts # Server management exports
│ │ ├── process.ts # Valheim process wrapper
│ │ ├── watchdog.ts # Crash detection and auto-restart
│ │ ├── logs.ts # Log parsing and streaming
│ │ └── commands.ts # Runtime admin command execution
│ │
│ ├── 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
│ │
│ └── 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
`$3
#### 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
$3
`mermaid
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
`$3
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. |$3
| 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 |$3
`bash
Install dependencies
npm installRun in development mode (with live reload)
npm run devRun tests
npm testType check
npm run typecheckLint and format
npm run lint
npm run formatBuild bundle
npm run buildRun built version
node dist/main.js --helpOr use npm start (builds automatically)
npm start -- --help
`> Note: The project uses Biome for linting and formatting.
$3
- Node.js 22.x or later
- npm 10.x or later
---
Troubleshooting
Run
npm start -- doctor to automatically diagnose common issues.$3
#### 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:
`bash
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/steamcmd@1.1.0. 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-packageManual fix (if needed):
`bash
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:
`bash
# 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:
`bash
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:
`bash
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
$3
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`---
This repo is open source and free to use