K.E.Y.S.T.O.N.E.

K.E.Y.S.T.O.N.E. consists of three crates inside the workspace: crates/core (process spawners, PTY, event loop, resource limits), crates/daemon (node REST/WS server, filesystem, embedded Lua 5.4), and crates/web (central panel, SQLite auth, remote manager, proxy).

1.1 Building From Source

Requires Rust (Cargo) and a C toolchain (for vendored Lua 5.4). Node.js is required to build the Svelte 5 + Vite frontend.

# Build daemon binary only
cargo build --release --features demon --bin daemon

# Build panel binary only
cargo build --release --features web --bin panel

# Build both binaries (full = demon + web)
cargo build --release --features full

# Build Web UI (outputs to webui/, served automatically by panel)
cd webui-src && npm install && npm run build

1.2 Bootstrap & Launch

The panel will not start unless at least one active administrator exists in its SQLite database. Passwords must be at least 12 UTF-8 bytes and are hashed with Argon2id.

# 1. Start the daemon
cp daemon.toml.example daemon.toml
./target/release/daemon daemon.toml

# 2. Configure panel & bootstrap administrator
cp panel.toml.example panel.toml
cp remotes.toml.example remotes.toml
./target/release/panel account bootstrap --username admin

# 3. Start panel (default http://127.0.0.1:24000)
./target/release/panel

2.1 Daemon Configuration (daemon.toml)

name = "daemon-1"
listen = "127.0.0.1:24444"
token = ""                # empty token is allowed ONLY on loopback
fs_root = "."             # all API paths and instance cwd resolve inside this root
data_dir = "./data"       # stores instance-<uuid>.json records
# cgroup_root = "/sys/fs/cgroup/keystone"
max_file_bytes = 1073741824
preset_http_allowed_origins = ["https://api.papermc.io"]

2.2 Panel Configuration (panel.toml) & Environment

listen = "127.0.0.1:24000"
database = "panel.db"
locales_dir = "locales"
presets_dir = "presets"
secure_cookies = false # set true when publishing panel over HTTPS

2.3 Remote Daemons (remotes.toml)

By default, plain http:// is allowed only for loopback addresses (127.0.0.1, ::1, localhost). Remote nodes over the network require https:// unless --allow-insecure-remotes is enabled.

[[remotes]]
id = "local"
name = "Local daemon"
url = "http://127.0.0.1:24444"
token = ""

[[remotes]]
id = "node2"
name = "Production Node EU"
url = "https://node2.example:24444"
token = "super-secret-bearer-token"

Login establishes a 12-hour HttpOnly; SameSite=Strict cookie session (keystone_session). Every state-changing request (POST, PUT, PATCH, DELETE) additionally verifies both the X-CSRF-Token header and the HTTP Origin header.

Role-Based Grants (Restricted Users)

Administrators manage accounts in the Account tab. A restricted user sees only explicitly granted resources. For an allowed instance, a restricted user can start and stop (and view read-only installation terminals), while configuration changes, force-kill, and deletion remain admin-only.

Runtime Fluent Localization

The frontend contains no hardcoded translation bundles. The panel loads <locales_dir>/<code>/messages.ftl and meta.json, serves them via GET /api/locales/:code with ETag caching, and hot-reloads changes every 2 seconds without restarting.

Each instance is stored on the daemon in <data_dir>/instance-<uuid>.json. Every configuration must include a resources object:

{
  "resources": {
    "cpu_percent": 150,
    "cpu_affinity": [0, 2],
    "memory_bytes": 2147483648
  },
  "nickname": "my-server",
  "start_command": "java -jar server.jar nogui",
  "stop_command": "stop",
  "stop_timeout": 30,
  "cwd": "servers/my-server",
  "ie": "utf-8",
  "oe": "utf-8",
  "pty": true,
  "cols": 120,
  "rows": 30,
  "auto_start": false,
  "auto_restart": true,
  "max_restarts": -1,
  "tags": ["minecraft"],
  "process_type": "general",
  "env": {
    "JAVA_HOME": "/opt/java"
  }
}

K.E.Y.S.T.O.N.E. enforces CPU and memory limits directly via OS kernel primitives without Docker. In resources, 100 in cpu_percent always means one full logical CPU regardless of host core count. Descendant processes share the instance's resource domain.

5.1 Platform Enforcement Matrix

5.2 Linux cgroups v2 Delegation (Unprivileged / runit)

No systemd or D-Bus dependency is used. When running as root, the daemon automatically prepares its cgroup v2 subtree. For an unprivileged keystone service user, delegate a subtree with separate daemon and instances leaves:

echo '+cpu +cpuset +memory' > /sys/fs/cgroup/cgroup.subtree_control
mkdir -p /sys/fs/cgroup/keystone/daemon /sys/fs/cgroup/keystone/instances
echo '+cpu +cpuset +memory' > /sys/fs/cgroup/keystone/cgroup.subtree_control
chown keystone:keystone /sys/fs/cgroup/keystone \
  /sys/fs/cgroup/keystone/cgroup.procs \
  /sys/fs/cgroup/keystone/cgroup.subtree_control \
  /sys/fs/cgroup/keystone/instances \
  /sys/fs/cgroup/keystone/instances/cgroup.procs \
  /sys/fs/cgroup/keystone/instances/cgroup.subtree_control

6.1 Daemon REST API (/api/v1)

Protected by Authorization: Bearer <token> header.

6.2 Panel REST API (/api)

6.3 Terminal WebSocket Protocol

Connect via subprotocol keystone to GET /api/terminal?remote=<id>&instance=<uuid>&cols=120&rows=30&readonly=false. Binary frames carry raw stdin/stdout bytes; JSON text frames carry control events:

// Client -> Server (resize PTY)
{ "resize": [120, 30] }

// Server -> Client (lifecycle events)
{ "event": "opened" }
{ "event": "stopped", "exit_code": 0 }
{ "event": "failure", "error": "..." }