ConnectRemote control for uebliche servers

What is Connect? ​

Connect is the bridge between dash.uebliche.net and your running server. It polls the public API for approved actions and executes them in-game.

For Uebliche-managed play, Connect also participates in the canonical join path from Launcher to Public API, Gateway, and Gameserver. The MVP join contract defines the ticket handoff and IDs used by the next Hide and Seek vertical slice.

• MVP join contract

Required setup ​

• Install the Connect mod or plugin for your loader.
• Configure the API endpoint and (optional) network metadata.
• On first start, Connect registers the server and stores credentials in connect.json.
• Make sure the server owner has assigned permissions in the public API.

Tip: override the API base via JVM start options, for example -DCONNECT_API_BASE=http://localhost:8080/v1 or -Dconnect.apiBase=http://localhost:8080/v1.

When CONNECT_GATEWAY_ENABLED stays enabled, the Paper and Velocity plugins publish the live server or proxy listener to the Gateway control plane automatically, without relying on the older static CONNECT_GATEWAY_TARGET_* target override path.

Local agent ​

For host-level actions and reduced API connections, deploy the Connect Agent on the server host and point Connect to the agent instead of the public API. The agent proxies /v1/connect/* to the API, caches permissions for short outages, and exposes host metrics/actions for Dash.

Default agent port: 47200.

Installations run the bootstrapper (uebliche-agent-bootstrap) as the system service. The bootstrapper fetches the update manifest, verifies downloads, and restarts the agent with the latest build.

Dash offers dedicated host onboarding under Hosts:

• Native host is the default path and installs the agent directly on Linux or Windows.
• Docker service is the optional Linux path; one agent container manages many direct server child processes inside the container.

In both cases, managed Minecraft servers stay on the direct agent-supervised process path. Docker is never the per-server runtime model.

Networks ​

Connect can group multiple servers into a shared network via a networkKey. Reuse the same key for servers that should appear together (for example per game mode or region).

Actions ​

Connect currently supports:

• Kick players.
• Send chat or system messages.
• List online players.
• Report basic performance data.
• Velocity-only server management (list, add, remove registered proxy servers).

In-game status ​

Use /connect status in-game to see the current connection state, last poll result, and settings stream status.

JoinMe ​

JoinMe is available on Paper and Fabric. Use /joinme to open the JoinMe menu and start or stop a session. JoinMe requires a game-side integration that registers a JoinMeContextProvider so Connect can publish the current match metadata and player counts to the API.

Settings stream ​

Connect can subscribe to the settings stream and apply live updates for a named source (for example hub). Updates can also be published back to the API so dash can keep an editable history of configuration changes.

Temporary instances ​

Set CONNECT_TEMP_INSTANCE=1 to mark a server as a temporary instance. You can optionally set CONNECT_TEMPLATE_ID to link the instance to a template server. Dash also supports setting temp: true in the connect settings source. Temporary instances are removed after about 15 minutes without a heartbeat.

Connect supports a readable server alias via CONNECT_SERVER_NAME (stored in connect.json after registration). The /connect status command prints the server name alongside the server id.

Agent permission preload ​

The Connect Agent can preload all permissions for a server by fetching the allowed user list and batch permissions from the API. This keeps permission checks available even when the API is temporarily unreachable and reduces per-user API calls.

Install ​

Native Linux host:

curl -fsSL https://install.uebliche.net/agent | sh

Native Windows host (manual bootstrap install):

$dest = "C:\\Uebliche\\agent"
New-Item -ItemType Directory -Force -Path $dest | Out-Null
Invoke-WebRequest `
  -Uri "https://update.uebliche.net/agent/release/windows-x86_64/uebliche-agent.zip" `
  -OutFile "$dest\\uebliche-agent.zip"
Expand-Archive -Path "$dest\\uebliche-agent.zip" -DestinationPath $dest -Force
& "$dest\\uebliche-agent-bootstrap.exe"

Optional Linux Docker service:

docker run --rm \
  -v /etc/uebliche/agent:/etc/uebliche/agent \
  -v /var/lib/uebliche/managed-servers:/var/lib/uebliche/managed-servers \
  -v /var/cache/uebliche/managed-servers:/var/cache/uebliche/managed-servers \
  -e AGENT_CONFIG=/etc/uebliche/agent/agent.toml \
  -e AGENT_MANAGED_SERVERS_RUNTIME_MODE=container \
  -e AGENT_MANAGED_SERVERS_HOSTING_MODE=direct \
  -e AGENT_MANAGED_SERVERS_ENABLED=true \
  -e AGENT_MANAGED_SERVERS_PUBLISH_VIA_CONNECT_GATEWAY=true \
  -e AGENT_HOST_CREDENTIALS_PATH=/etc/uebliche/agent/host.json \
  -e AGENT_SERVER_ROOT=/var/lib/uebliche/managed-servers \
  -e AGENT_CACHE_ROOT=/var/cache/uebliche/managed-servers \
  ghcr.io/uebliche/agent:latest

This container mode does not require per-server containers or public Docker port mappings. Player traffic still goes out through Connect Gateway.

In-game permissions ​

Connect checks in-game permissions for user-triggered actions:

• uebliche.connect.status
• uebliche.connect.command.kick
• uebliche.connect.command.message
• uebliche.connect.command.list_players
• uebliche.connect.command.list_performance
• uebliche.connect.command.list_servers (Velocity only)
• uebliche.connect.command.add_server (Velocity only)
• uebliche.connect.command.remove_server (Velocity only)
• uebliche.connect.joinme (Paper only)
• uebliche.connect.settings.write
• uebliche.connect.settings.<source>.write (scoped settings updates)

Downloads ​

Feature checklist ​

Track feature progress in the checklist.

• Feature checklist

Feature highlights ​

• Server actions
• Live settings
• Multi-loader support
• Permission aware
• Add feature checklist page to track project progress.
• Add extension registration and action hooks to the Connect service.
• Show server aliases in the Connect status command output.
• Support temporary instances and template IDs for Connect servers.
• Publish hub settings schemas to Connect so Dash can render typed fields.
• Add JoinMe SDK plumbing and API calls for create, heartbeat, and close.
• Add /joinme menu support for Paper and Fabric servers.
• Document the Docker-service container run command for the Connect Agent.
• Add single-use network join tokens and host join endpoint for the Connect Agent. (api 07cd76c)
• Add Dash hosts view with a cloud-init generator for agent installs. (dash 5874a78)
• Document the bootstrapper-driven auto-update flow for the Connect Agent. (agent f6654fb)
• Document the public install scripts for the Connect Agent. (install 2a59b2f)
• Document the Windows manual bootstrap install path and add native Windows host packaging for the Connect Agent. (agent local)
• Document Connect Agent permission preload and batch permission fetch support. (agent e44fd75)
• Document the local Connect Agent gateway for proxying Connect traffic and host management.
• Add Velocity-only server management actions (list, add, remove registered proxy servers).
• Allow overriding API base via JVM start options (system properties).
• Add Connect server bridge for dash-triggered actions.
• Add multi-loader builds for Fabric, NeoForge, Paper, and Velocity.
• Add permission-aware API integration for remote actions.
• Add in-game permission checks for connect commands and settings updates.
• Add /connect status command for connection diagnostics.
• Add automatic server registration with connect.json and network key support.