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)[https://ascii-motion.app/]—why settle for static ASCII art when you can have animated ASCII art?
- State Management: Zustand

Quick Start

$3

``bash


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:

`bash


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.

$3

`bash


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.

$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 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.

$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-package

Manual 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`
- Relevant error messages
- Your platform and Node.js version

---

Repo details

This repo is open source and free to use