IPC Channels Reference — ServerPilot Electron Bridge

ServerPilot’s renderer process (the React UI) never has direct access to the filesystem or Node.js APIs. Instead, it communicates with the Electron main process through a tightly restricted IPC bridge that is injected into the renderer as window.serverPilot via Electron’s contextBridge. The bridge exposes exactly two methods: invoke(channel, payload) for request-response interactions (returns a Promise), and on(channel, callback) for subscribing to server-pushed events (returns an unsubscribe function). Any channel not in the explicit allow-list throws immediately — nothing is leaked by accident.

// Invoke a channel (returns a Promise)
window.serverPilot.invoke('server:start', serverId)
  .then(state => console.log(state));

// Listen for push events (returns unsubscribe function)
const off = window.serverPilot.on('server:log', (data) => {
  console.log(data.message);
});
// Later: off(); to unsubscribe

The React layer wraps these calls in src/services/api.js so application code imports api.invoke and api.on instead of referencing window.serverPilot directly.

App & Settings

`app:data:get`

Returns the full application state on startup. Call this once when the UI mounts to hydrate the server list and global settings. Payload: none

servers

Server[]

required

Array of all saved server configurations.

settings

Settings

required

Merged settings object (user overrides merged on top of defaults).

`settings:update`

Merges a partial Settings object into the persisted settings store and returns the full merged result.

settings

Partial<Settings>

required

Any subset of the Settings object. Only provided keys are overwritten.

(return)

Settings

The complete, merged Settings object after the update.

`dialog:select-folder`

Opens the native Windows folder-picker dialog and returns the selected path, or null if the user cancels. Payload: none

(return)

string | null

Absolute path to the selected folder, or null if cancelled.

`dialog:select-file`

Opens the native Windows file-picker dialog with optional file-type filters.

filters

Array<{ name: string, extensions: string[] }>

Optional array of file type filters (e.g. [{ name: 'Java Executables', extensions: ['exe'] }]). Defaults to executables and JARs.

(return)

string | null

Absolute path to the selected file, or null if cancelled.

Server Management

`server:add`

Persists a new server configuration. The main process assigns a UUID id and merges defaults from the current global settings (Java path, RAM, Playit auto-start).

server

Partial<Server>

required

Server configuration object. id, createdAt, and updatedAt are generated automatically.

(return)

Server

The newly created server object including its generated id.

`server:update`

Updates an existing server configuration. The id field is required to locate the record.

server

Server

required

Full or partial server object. Must include id.

(return)

Server

The updated server object.

`server:remove`

Removes a server configuration from the store. Does not delete files on disk.

string

required

The UUID of the server to remove.

(return)

Server[]

The remaining server array after removal.

`server:detect`

Scans a folder for Minecraft server JARs and configuration files. Prefers Paper over Fabric over Forge over Vanilla when multiple JARs are found.

folderPath

string

required

Absolute path to the folder to inspect.

jarName

string

Filename of the detected JAR (e.g. paper-1.21.4-191.jar), or empty string if none found.

serverType

'Paper' | 'Fabric' | 'Forge' | 'Vanilla' | 'Unknown'

Inferred server type based on the JAR filename.

hasProperties

boolean

Whether server.properties exists in the folder.

hasOps

boolean

Whether ops.json exists in the folder.

hasWhitelist

boolean

Whether whitelist.json exists in the folder.

`server:start`

Launches the Minecraft server process for the given server. Builds the Java command from the server’s javaPath, ramMin, ramMax, jarName, and jvmArgs — stripping any arguments that ServerPilot manages itself. If autoStartPlayit is enabled and a valid Playit executable path is configured, Playit is launched simultaneously.

string

required

The UUID of the server to start.

serverId

string

UUID of the server.

status

'STARTING' | 'ONLINE' | 'STOPPING' | 'OFFLINE' | 'CRASHED'

Current lifecycle status.

pid

number | null

OS process ID of the Java process.

playitPid

number | null

OS process ID of the Playit process, if running.

startedAt

number | null

Unix timestamp (ms) of when the server was started.

playitStatus

string

Current Playit status string (e.g. PLAYIT ONLINE, PLAYIT STOPPED).

crashReason

string

Non-empty if the server is in the CRASHED state.

lastLogs

string[]

Up to 30 most recent cleaned log lines.

`server:stop`

Sends the stop command to the server’s stdin and starts a 15-second force-kill timer. If the process does not exit within 15 seconds, it is terminated via taskkill.exe /PID <pid> /T /F.

string

required

The UUID of the server to stop.

(return)

ServerState

Public server state at the moment the stop was requested (same shape as server:start).

`server:restart`

Performs a graceful stop (waits for the process to exit) and then starts the server again. Returns the public state after the new start.

string

required

The UUID of the server to restart.

(return)

ServerState

Public server state after the restart (same shape as server:start).

`server:kill`

Force-kills the server process after a 3-second grace period instead of the normal 15 seconds. Use for unresponsive servers.

string

required

The UUID of the server to force-kill.

(return)

ServerState

Public server state (same shape as server:start).

`server:command`

Writes a command string to the server’s stdin (appends \n). Also emits a server:log event with level: 'command' so the console UI shows it in-line.

string

required

The UUID of the target server.

command

string

required

The command to send, e.g. op Steve or say Hello world.

(return)

boolean

Always true on success. Throws if the server is not running.

`server:open-folder`

Opens the server’s folder in Windows Explorer using shell.openPath.

string

required

The UUID of the server.

(return)

boolean

Always true.

`server:open-terminal`

Opens a cmd.exe window pre-navigated to the server’s folder.

string

required

The UUID of the server.

(return)

boolean

Always true.

Metrics

`metrics:get`

Polls pidusage for the current CPU and memory consumption of the server’s Java process, appends a data point to the in-memory history (capped at 40 points), and also emits a server:metrics push event so the dashboard chart updates automatically. Returns OFFLINE defaults if the server is not running.

string

required

The UUID of the server to measure.

status

string

Current server status.

cpu

number

CPU usage as a percentage (1 decimal place).

memory

number

Process RSS memory in MB.

systemMemory

number

Total system used memory in MB.

uptime

number

Seconds elapsed since the server was started.

pid

number | null

Java process ID.

playitPid

number | null

Playit process ID, if running.

playitStatus

string

Current Playit status string.

tps

number

Reported TPS (currently fixed at 20 — future plugin integration).

players

number

Number of currently online players.

history

Array<{ time: string, cpu: number, memory: number }>

Up to 40 historical data points for the sparkline chart.

crashReason

string

Non-empty when the server has crashed.

lastLogs

string[]

Up to 30 most recent log lines.

File Manager

`files:list`

Lists the contents of a directory inside the server folder, sorted directories-first then alphabetically by name.

string

required

Server UUID.

relativePath

string

Path relative to the server’s root folder. Omit or pass empty string for the root.

(return)

FileEntry[]

Array of entries: { name, relativePath, isDirectory, size, updatedAt } — directories appear before files.

`files:read`

Reads a text file inside the server folder and returns its content along with a language hint for Monaco Editor. Supported extensions: .yml, .yaml, .json, .txt, .properties, .log, .md, .cfg, .conf, .toml. Files larger than 4 MB are rejected.

string

required

Server UUID.

relativePath

string

required

Path to the file relative to the server root.

content

string

UTF-8 file content.

language

string

Language identifier for Monaco (e.g. json, yaml, properties).

`files:write`

Writes a UTF-8 string to an existing file inside the server folder. Payloads exceeding 4 MB are rejected.

string

required

Server UUID.

relativePath

string

required

Path to the file relative to the server root.

content

string

required

Full UTF-8 file content to write.

(return)

boolean

Always true on success.

`files:create`

Creates a new empty file or a new directory (including intermediate directories) inside the server folder.

string

required

Server UUID.

relativePath

string

required

Desired path relative to the server root.

type

'file' | 'folder'

required

Whether to create a file or a directory.

(return)

boolean

Always true on success.

`files:delete`

Recursively deletes a file or directory inside the server folder.

string

required

Server UUID.

relativePath

string

required

Path relative to the server root.

(return)

boolean

Always true on success.

`files:rename`

Renames a file or directory. The new name must not contain / or \ — only a simple filename is accepted.

string

required

Server UUID.

relativePath

string

required

Current path relative to the server root.

nextName

string

required

New filename (no path separators allowed).

(return)

boolean

Always true on success.

Properties

`properties:get`

Reads server.properties (parsed into a key-value map) and the three standard JSON files (ops.json, whitelist.json, banned-players.json) from the server folder. Returns empty defaults for any file that does not exist yet.

string

required

Server UUID.

properties

Record<string, string>

All entries from server.properties as a flat key-value object (comments and blank lines stripped).

json

object

Object with keys ops.json, whitelist.json, and banned-players.json, each containing the parsed array (or [] if the file is missing or malformed).

`properties:save`

Writes server.properties and up to three JSON files back to disk. A #Edited by ServerPilot <timestamp> comment is prepended to server.properties. Only ops.json, whitelist.json, and banned-players.json are accepted as JSON targets — any other key in the json object is silently skipped.

string

required

Server UUID.

properties

Record<string, string>

required

Key-value map to write as server.properties.

json

object

required

Object with keys matching the allowed filenames and their corresponding arrays as values.

(return)

boolean

Always true on success.

Backups

`backups:list`

Returns all .zip files from the server’s backups/ subfolder, sorted newest-first by creation time.

string

required

Server UUID.

(return)

BackupEntry[]

Array of { name, fullPath, size, createdAt } where createdAt is a Unix timestamp in milliseconds.

`backups:create`

ZIPs the entire server folder (excluding the backups/ subfolder itself) into a timestamped archive at <serverFolder>/backups/<serverName>-<timestamp>.zip using maximum compression. Emits a desktop notification when complete.

string

required

Server UUID.

fullPath

string

Absolute path to the created ZIP file.

name

string

Filename of the ZIP (e.g. MyServer-2025-01-15T10-30-00-000Z.zip).

`backups:restore`

Extracts a ZIP backup over the server folder. The backupPath must be inside the server’s own backups/ subdirectory — paths outside this location are rejected.

string

required

Server UUID.

backupPath

string

required

Absolute path to the .zip file to restore. Must reside in <serverFolder>/backups/.

(return)

boolean

Always true on success.

Push Event Channels

Subscribe to these channels with window.serverPilot.on(channel, callback). Each call returns an unsubscribe function — call it when the component unmounts to prevent memory leaks.

const off = window.serverPilot.on('server:log', (data) => {
  appendToConsole(data);
});

// In cleanup / useEffect return:
off();

`server:log`

Emitted for every line of output from the Minecraft process (stdout/stderr) and the Playit process. Also emitted when a command is sent via server:command.

serverId

string

UUID of the originating server.

level

'info' | 'error' | 'warn' | 'command'

Severity / type of the log line.

source

'server' | 'playit'

Whether the line came from the Minecraft process or the Playit process.

message

string

Cleaned log text (ANSI escape codes and non-printable characters stripped).

string

ISO 8601 timestamp of when the line was received.

`server:status`

Emitted whenever the server’s lifecycle status changes (e.g. STARTING → ONLINE, ONLINE → STOPPING, etc.).

serverId

string

UUID of the server.

status

'STARTING' | 'ONLINE' | 'STOPPING' | 'OFFLINE' | 'CRASHED'

New status.

pid

number | null

Java process ID.

playitPid

number | null

Playit process ID.

startedAt

number | null

Unix timestamp (ms) of server start.

playitStatus

string

Current Playit status string.

crashReason

string

Non-empty when status is CRASHED.

lastLogs

string[]

Up to 30 most recent log lines.

`server:metrics`

Emitted automatically by metrics:get every time the dashboard polls for metrics. Same payload as the metrics:get return value plus serverId.

serverId

string

UUID of the server.

status

string

Current status.

cpu

number

CPU % (1 decimal place).

memory

number

RSS memory in MB.

systemMemory

number

Total system used memory in MB.

uptime

number

Seconds since start.

pid

number | null

Java process ID.

playitPid

number | null

Playit process ID.

playitStatus

string

Current Playit status string.

tps

number

Reported TPS.

players

number

Online player count.

history

Array<{ time: string, cpu: number, memory: number }>

Up to 40 historical data points.

crashReason

string

Non-empty if crashed.

lastLogs

string[]

Up to 30 recent log lines.

`server:players`

Emitted whenever the online player list changes (join, leave, kick, chat, etc.). The online array is sorted alphabetically by username. activity contains the 150 most recent events in reverse-chronological order.

serverId

string

UUID of the server.

online

Player[]

Array of currently online players, each with username, joinTime, status, ping, lastActivity, lastActivityText, dimension, and uuid.

onlineCount

number

Length of the online array.

activity

Activity[]

Up to 150 recent player activity events (newest first). Each event has id, at, type, username, and text.

`toast`

Emitted for every desktop notification shown by Notification.show(). The UI can mirror these as in-app toast messages.

title

string

Notification title (e.g. Server online).

body

string

Notification body (e.g. MyServer finished startup.).

Get Started

Setup Guide

Features

Configuration

Reference

Documentation Index

​App & Settings

​app:data:get

​settings:update

​dialog:select-folder

​dialog:select-file

​Server Management

​server:add

​server:update

​server:remove

​server:detect

​server:start

​server:stop

​server:restart

​server:kill

​server:command

​server:open-folder

​server:open-terminal

​Metrics

​metrics:get

​File Manager

​files:list

​files:read

​files:write

​files:create

​files:delete

​files:rename

​Properties

​properties:get

​properties:save

​Backups

​backups:list

​backups:create

​backups:restore

​Push Event Channels

​server:log

​server:status

​server:metrics

​server:players

​toast

Build docs developers (and LLMs) love

App & Settings

`app:data:get`

`settings:update`

`dialog:select-folder`

`dialog:select-file`

Server Management

`server:add`

`server:update`

`server:remove`

`server:detect`

`server:start`

`server:stop`

`server:restart`

`server:kill`

`server:command`

`server:open-folder`

`server:open-terminal`

Metrics

`metrics:get`

File Manager

`files:list`

`files:read`

`files:write`

`files:create`

`files:delete`

`files:rename`

Properties

`properties:get`

`properties:save`

Backups

`backups:list`

`backups:create`

`backups:restore`

Push Event Channels

`server:log`

`server:status`

`server:metrics`

`server:players`

`toast`