Developer & Security

Remote Control API

When Remote Control is active, PocketMC runs an embedded ASP.NET Core Kestrel web server on port 25580. It serves the bundled web dashboard and provides a REST and WebSocket API for controlling your Minecraft servers programmatically.

Base Address: http://127.0.0.1:25580 · Authentication: Cookie session via POST /api/login

Authentication and Sessions

To interact with protected API endpoints, authenticate with your administrator or sub-user credentials at /api/login. Upon successful authentication, the server sets a session cookie named PocketMCRemoteAuth.

POST /api/login
POST /api/login HTTP/1.1
Host: 127.0.0.1:25580
Content-Type: application/json

{
  "username": "admin",
  "password": "your-password"
}
200 OK Response
HTTP/1.1 200 OK
Set-Cookie: PocketMCRemoteAuth=...; path=/; samesite=strict; httponly; max-age=86400

{
  "success": true
}

The login endpoint limits requests to 5 failed attempts per minute per IP address. Exceeding this rate returns HTTP 429.

Daemon Status and Permissions

Query server status, network endpoints, and the active session's permission flags:

GET /api/status
GET /api/status HTTP/1.1
Cookie: PocketMCRemoteAuth=...
200 OK Response
{
  "enabled": true,
  "hostRunning": true,
  "port": 25580,
  "accessMode": 0,
  "localUrls": ["http://127.0.0.1:25580", "http://192.168.1.50:25580"],
  "publicUrl": null,
  "tunnelRunning": false,
  "allowRemoteConsoleCommands": true,
  "allowRemotePlayerActions": true,
  "allowRemoteServerSettings": true,
  "allowRemoteServerAddons": true,
  "allowRemoteFileManager": true,
  "allowRemoteServerBackups": true
}

Instance Lifecycle Endpoints

Control server processes using their instance GUID:

MethodEndpointDescription
GET/api/instancesLists all instances permitted for the current authenticated user account.
GET/api/instances/{id}/statusReturns runtime status, player counts, CPU percentage, and memory usage in bytes.
POST/api/instances/{id}/startSpawns the server process within its Win32 Job Object sandbox.
POST/api/instances/{id}/stopSends graceful stop command with RCON save-flush before process exit.
POST/api/instances/{id}/restartExecutes a clean shutdown followed by an automatic reboot.

Live Console and WebSockets

Terminal output can be retrieved through polling or live WebSocket streaming:

  • Buffered Output: GET /api/instances/{id}/console/history returns recent console output lines stored in the server's in-memory circular buffer.
  • Command Input: POST /api/instances/{id}/console/command sends a command to the server STDIN. Body format: {"command": "say Hello"}. Submissions are limited to 30 requests per minute per instance.
  • WebSocket Stream: Connect your WebSocket client to /ws/instances/{id}/console with the PocketMCRemoteAuth session cookie. PocketMC pushes log lines over the socket in real time and processes text messages sent over the socket as server commands.

Player Moderation and Settings

Manage players and configuration options remotely:

  • Player List: GET /api/instances/{id}/players returns online usernames and connection statistics.
  • Player Actions: POST /api/instances/{id}/players/{name}/{action} executes moderation actions. Valid actions are kick, ban, pardon, op, and deop. On Bedrock servers, ban commands update the internal pocketmc-bans.json sidecar.
  • Server Properties: GET /api/instances/{id}/properties returns current settings as a key-value object. PUT /api/instances/{id}/properties writes updated values back to the server.properties file.

Addons and Modifications

Manage plugins and mods over the API:

  • List Addons: GET /api/instances/{id}/addons lists installed plugins and mods, file sizes, and enabled states.
  • Uninstall Addon: POST /api/instances/{id}/addons/uninstall removes a mod or plugin file. Body format: {"fileName": "example.jar", "addonType": 0}.

Files and World Backups

Sandboxed filesystem access and backup controls:

  • List Files: GET /api/instances/{id}/files?path=plugins returns files and directories inside the specified path. Access outside the instance root directory is blocked.
  • Read Text File: GET /api/instances/{id}/files/content?path=server.properties retrieves file text. Files larger than 1 MB are rejected to preserve memory.
  • Save Text File: PUT /api/instances/{id}/files/content writes updated text back to disk. Body format: {"path": "server.properties", "content": "..."}.
  • Upload File: POST /api/instances/{id}/files/upload accepts multipart form uploads up to 100 MB per file directly into the target directory.
  • Delete File: DELETE /api/instances/{id}/files?path=... permanently removes the designated file or directory.
  • Backup History: GET /api/instances/{id}/backups lists archive files with file size, creation timestamp, and SHA-256 integrity hash.
  • Create Backup: POST /api/instances/{id}/backups initiates an immediate background snapshot with an automatic RCON save-flush if the server is running.