Getting Started

An installation, setup, and operation guide for first-time Saba-chan users. Covers how things actually behave under the hood, plus things to watch out for.

Getting Started

This document is aimed at first-time users of Saba-chan. If you're not yet thinking about reading the source code or building your own modules, this page plus the Discord Bot and Troubleshooting pages alone are more than enough to run a server.

1. Requirements

  • Operating System: Windows 10 / 11 64-bit. Linux and macOS installers are not currently distributed.
  • Disk: ~300 MB for Saba-chan itself + ~200 MB for the portable Python/Node runtimes + the original game server files (anywhere from a few GB to tens of GB depending on the game).
  • Memory: 4 GB minimum. Game servers like Minecraft and Palworld additionally require 1–8 GB on top of Saba-chan itself.
  • Administrator privileges: Once, when running the installer. Day-to-day usage afterwards does not need admin.

💡 Saba-chan never touches the registry and never modifies your PATH environment variable. Every runtime and every config is stored under a single folder, %APPDATA%\saba-chan, so deleting that folder later removes Saba-chan cleanly.

2. Download & Install

  1. From GitHub Releases, download the saba-chan-installer-windows-x64.zip from the latest release.
  2. Unzip it. Inside is a Tauri-based installer (.exe). Run it and follow the prompts.
  3. Internally, the installer performs the following work. It requires a network connection and may take a few minutes to complete.
    • Downloads portable Python and creates a venv (runtime/python-standalone/)
    • Downloads portable Node.js (runtime/node-portable/)
    • Lays out the daemon, GUI, CLI, updater, Discord bot, locales, and other components
    • Records each component's version against installed-manifest.json for verification
  4. When installation finishes, the GUI (saba-chan-gui) launches automatically.

Damage recovery: If installation was interrupted or files got corrupted, just run the installer again. The setup_python_with_repair() / setup_node_with_repair() logic re-downloads only the damaged parts. You don't need to manually delete folders.

3. Understanding the Saba-chan Architecture

Skipping this section often leads to confusion like "I closed the window, why is the game server still running?" It's short, please give it a read.

┌──────────────┐   HTTP + X-Saba-Token    ┌─────────────────┐
│   GUI        │ ───────────────────────▶ │                 │
│  (Electron)  │                          │                 │
└──────────────┘                          │                 │
                                          │  saba-chan.exe  │
┌──────────────┐   HTTP + X-Saba-Token    │    (daemon)     │
│   CLI (TUI)  │ ───────────────────────▶ │                 │
└──────────────┘                          │                 │
                                          │  127.0.0.1:57474│
┌──────────────┐   HTTP + X-Saba-Token    │                 │
│ Discord Bot  │ ───────────────────────▶ │                 │
└──────────────┘                          └─────────────────┘
                                                  │
                                                  ▼ spawns processes
                                          ┌─────────────────┐
                                          │ game server /   │
                                          │ module          │
                                          │ (java, palworld │
                                          │  server exe …)  │
                                          └─────────────────┘
  • Daemon (saba-chan.exe) — The core that actually launches game servers, manages their state, and collects logs. It exposes an HTTP API on the local address 127.0.0.1:57474.
  • GUI — A "remote control" that calls the daemon API. Closing the window does not stop the daemon.
  • CLI / Discord Bot — Yet more remote controls that all call the same API.

When you close and reopen the GUI, it instantly reconnects to the game server processes that the daemon was already holding, and the logs continue streaming. To actually shut down a game server, click the "Stop" button inside the GUI.

4. Creating Your First Server (using the GUI)

When Saba-chan is launched for the first time, the server list is empty. Proceed in this order:

  1. Choose a module — Pick the game Saba-chan supports (3 are bundled by default: Minecraft, Palworld, Project Zomboid; others can be added by downloading from the module manifest). Each module displays badges for its required extensions, which will be auto-installed if needed.
  2. Choose a version — A list of versions, fetched from the GitHub manifest, appears. Picking the latest stable release is fine.
  3. Set the instance name and install path — The name is any string that helps you tell servers apart. The install path is the directory where the original game files will live (the default is recommended).
  4. Start installation — The daemon does the following in order:
    • Checks dependent extensions (e.g. SteamCMD will be auto-installed for Palworld and Zomboid)
    • Persists instance metadata to instances.json
    • Runs the server.post_create hook (can be async; progress is reflected on the progress bar by polling GET /api/provision-progress/:name)
    • Downloads/clones the original game files (decided by the module + extensions: SteamCMD/HTTP/Docker/etc.)
    • For games requiring an EULA (Minecraft), runs the agreement step.
  5. Start — Pressing the Start button enters server.pre_start → process spawn (get_launch_command) → state-monitoring loop. Server logs flow into the GUI console at a 2-second polling interval.

5. Behavior to know during operation

5.1 Stop timeout

When the user clicks Stop, the daemon attempts shutdown in the following order. The actual values are defined in src/supervisor/mod.rs.

  1. Graceful stop: Sends the module's stop_command (e.g., Minecraft stop, Palworld Shutdown, Zomboid quit) over the appropriate channel — RCON, REST, or stdin. Waits 30 seconds by default. This can be overridden with graceful_stop_timeout in the module's module.toml.
  2. Force kill: If the process still doesn't exit, the entire process tree is forcefully killed after 5 seconds.
  3. Stop cooldown: Right after stopping, automatic detection is suppressed for 30 seconds so that a "process suddenly disappeared" event is not misinterpreted as a crash.

5.2 Crash handling

When a process dies unexpectedly, the state machine transitions Running → Crashed (code: src/supervisor/state_machine.rs). The restart policy is dictated by the module's [docker].restart field, defaulting to "unless-stopped". In other words, unless the user explicitly stops it, automatic restarts are attempted. There's currently no explicit cap on the restart count in code, so if you want to break the loop, stop the server manually or change the module setting to "no" / "on-failure" or similar.

5.3 Log location

  • Daemon logs: %APPDATA%\saba-chan\logs\
  • Per-instance console output: kept in the daemon's memory up to the most recent consoleBufferSize (default 10 000 lines). The GUI does cursor-based polling via GET /api/instance/:id/console?since=….

6. Next Steps