Configuration File Guide

All of Saba-chan's settings and state live exclusively under the user folder %APPDATA%\saba-chan (= C:\Users\<your-name>\AppData\Roaming\saba-chan). This document summarizes which keys the actual code reads from the files inside it. We also distinguish between files you can safely edit by hand and files you should never touch.

1. Folder Structure

%APPDATA%\saba-chan\
├── settings.json              ← Shared GUI / daemon settings
├── bot-config.json            ← Discord bot settings (includes local / relay)
├── instances.json             ← The list of server instances you've created
├── .ipc_token                 ← UUID v4 used to authenticate daemon ↔ clients
├── .node_token                ← Cloud relay token (sbn_{hostId}.{secret})
├── extensionConfig.json       ← Per-extension user settings
├── extensions_state.json      ← Enabled/disabled state of each extension
├── modules/                   ← Installed Python modules
├── extensions/                ← Installed extensions
├── runtime/
│   ├── python-standalone/     ← Portable Python + venv
│   └── node-portable/         ← Portable Node.js
├── logs/                      ← Logs from the daemon, modules, and bot
└── updates/                   ← Updater staging area

You can override the root itself with the SABA_DATA_DIR environment variable, but doing so hurts portability and is generally not recommended.

2. settings.json — Shared GUI / Daemon

When the daemon boots, if no SABA_IPC_PORT environment variable is set, it reads ipcPort from this file; if that's also missing, it falls back to the default 57474. The GUI side mostly reads polling-interval and theme-related keys.

3. bot-config.json — Discord Bot

The Discord bot runs on the relay server, so there is no bot process on your PC. This file stores the prefix, aliases, and per-guild permissions you edit from the GUI; after pairing, Saba-chan automatically syncs them to the relay server as host metadata.

The Discord bot token is not something users handle. The bot runs with a token managed by the relay-server operator.

Command Syntax

사바쨩 <command> <module_or_alias> [arguments…]

• 사바쨩 start minecraft
• 사바쨩 stop mc (alias)
• 사바쨩 status palworld

There are 3 default built-in commands: start, stop, status. Additional commands such as music are provided by bot modules on the relay-server side.

4. instances.json — Your Server List

Stores the metadata and settings for each server instance you've created in the GUI. Example structure:

{
  "version": 2,
  "instances": [
    {
      "id": "instance_1",
      "name": "My Minecraft Server",
      "module_name": "minecraft",
      "installation_dir": "C:\\Servers\\Minecraft",
      "settings": {
        "port": 25565,
        "gamemode": "survival",
        "difficulty": "normal"
      },
      "ext_data": {
        "docker_enabled": false
      }
    }
  ]
}

• settings differs per module. For example, Palworld additionally holds REST credentials such as rest_password, while Zomboid stores an extra RCON port.
• ext_data is reserved storage for extensions. The Docker extension stores its docker_enabled flag here; SteamCMD stores app_id / beta / etc.

You should only hand-edit this file while the daemon is not running. Editing it during execution will cause divergence between disk and the daemon's in-memory state.

5. Token Files (.ipc_token / .node_token)

IPC Token Usage Example

GET /api/servers HTTP/1.1
Host: 127.0.0.1:57474
X-Saba-Token: 550e8400-e29b-41d4-a716-446655440000

• If you lose the token, delete the file and restart the daemon. A new UUID is issued and all clients re-read it.
• During development you can disable verification with the SABA_AUTH_DISABLED=1 environment variable. Never use this in production.

Node Token Usage Example (HMAC signing)

Authorization: Bearer sbn_{hostId}.{secret}
X-Request-Timestamp: 1714002600
X-Request-Nonce: <random UUID>
X-Request-Signature: HMAC_SHA256(
  METHOD + "\n" + URL_PATH + "\n" +
  TIMESTAMP + "\n" + NONCE + "\n" +
  BODY,
  secret
)

The relay server requires every request to pass Argon2 hash verification, a ±30-second timestamp window, a nonce duplication check, and HMAC verification.

6. Extension Settings (extensionConfig.json / extensions_state.json)

• extensions_state.json — enabled: true|false state for each extension.
• extensionConfig.json — The actual values for the keys each extension declares in its config_fields (manifest.json). Example: Docker's docker_host, etc.

The GUI's "Extensions" screen edits these files; the daemon receives PUT /api/extensions/:id/config calls and updates the file atomically.

7. Key Environment Variables

If you suspect you've broken something, stop the daemon first, then delete the offending file and relaunch the GUI. Most files will be regenerated with their defaults. Instance directories (the folders where the actual game files live) are preserved until you delete them yourself.