CTmine-client

ContainerMine Client — a real Minecraft Java client inside a Docker container, streamed live to your browser via noVNC.

A Docker web app that runs a real Minecraft Java client inside a container and displays it directly in your browser via noVNC. Ideal for parking an account AFK at a farm — no local Minecraft client or Java installation required.

The dashboard is a Vite + Vue 3 app, shipped inside the same container.

---

Architecture

Browser  ──HTTP/WS──▶  nginx (:8080)
                        ├── /            → Vue dashboard (static)
                        ├── /api/*       → Node status API (127.0.0.1:3000)
                        └── /websockify  → websockify (127.0.0.1:6080)
                                              │
                       supervisord manages ▼
                        Xvfb :0  →  x11vnc  →  websockify  →  Browser
                          ▲
                     Prism Launcher + real Minecraft client
                     (renders via software OpenGL/llvmpipe on Xvfb)

Why Prism Launcher instead of the official Mojang launcher? The Mojang launcher uses an embedded webview for the Microsoft login that regularly causes trouble inside a headless container. Prism starts the same vanilla client, is more container-friendly, and uses the device-code flow for login: note the code → open microsoft.com/link on any device → done.

---

Prerequisites

• Docker (with BuildKit) and Docker Compose v2
• ~2 GB of free disk space for the image
• A valid Microsoft account with a Minecraft license
• Chromium/Firefox (for WebGL & WebSockets in noVNC)

Building locally without Docker is not intended. If you only want to work on the dashboard, see Developing the Dashboard.

---

Quick Start

# 1. Create and adjust the env file
cp .env.example .env
#    Set PUID/PGID to `id -u` / `id -g` so that ./config belongs to you.

# 2. Build the image and start the stack
docker compose up -d --build

# 3. Open the dashboard
#    http://localhost:8080

---

First Login (one-time)

1. Open the dashboard → http://localhost:8080
2. Click “Start instance”. Prism Launcher opens in the VNC window.
3. In Prism, top right: Accounts → Add account → Microsoft.
4. Prism shows a code. On any device, open https://microsoft.com/link, enter the code and sign in with Microsoft.
5. Back in Prism: select the desired instance in the main window and click “Play”. Prism automatically downloads the matching Minecraft version + Java.
6. In the Minecraft main menu: Multiplayer → Add Server → enter your farm’s address → Connect.

From now on your account sits at the farm. The login is stored persistently in ./config/prism and survives docker compose down.

Tip: Before restarting the container, you can configure the correct farm hookup in Minecraft under Options → Controls (e.g. a trade/anti-AFK macro mod) — it will persist.

---

AFK Farm Setup

The concrete setup depends on your farm. Typical steps:

• Anti-AFK: jump/move periodically so the server doesn’t kick you. You can use a vanilla mechanism (e.g. a water stream that keeps you gently moving) or install a client mod such as Mouse Tweaks / Inventory Profiles. Mods are added via Prism into the respective instance.
• Auto-reconnect: some servers disconnect after hours. Consider a Reconnect mod.
• Keep the window open: as long as the dashboard is open, you can watch the client live. You can close the tab — Minecraft keeps running inside the container. Only the container needs to run.

---

Configuration (.env)

Variable	Default	Meaning
PUID / PGID	1000	UID/GID of the container user. Set to your host user’s id -u/id -g so that ./config belongs to you.
TZ	Europe/Berlin	Container time zone.
DISPLAY_WIDTH	1280	Width of the virtual display (MC resolution).
DISPLAY_HEIGHT	720	Height of the virtual display.
DISPLAY_DEPTH	24	Color depth (24 = 8-bit RGB).
WEB_PORT	8080	Browser-facing port.
VNC_PASSWORD	(empty)	Optional. Empty = no auth (local network only!).
X11VNC_EXTRA	see .env	Low-latency/input flags for x11vnc.

---

VNC Controls

Controls are tuned for Minecraft menus, chat, inventory and AFK farms. They are not intended for active PVP/mouselook — that is a fundamental VNC limitation (see below).

In the browser:

• Click into the picture → sets keyboard focus inside the game window (keys go to the game, not the browser).
• Release focus → click outside the picture (e.g. on the toolbar).
• Send Ctrl+Alt+Del to the container → button in the noVNC side menu (arrow on the left edge).
• Fullscreen → toolbar button; covers the whole page for Minecraft.
• Clipboard → automatically linked (copy login codes / server addresses directly between browser and container).

Configured automatically:

• resize=scale: noVNC scales the fixed Xvfb resolution to the window size. True live-resizing is not possible — x11vnc does not support SetDesktopSize requests. The base resolution is set via DISPLAY_WIDTH/DISPLAY_HEIGHT; you get 1:1 pixel mapping when the browser window matches the display resolution.
• reconnect=1: noVNC reconnects on its own after disconnects.
• Same-origin-only WebSocket: nginx checks that the Origin header of the browser handshake matches the host. Without this check, any web page could silently open a VNC connection to your dashboard.
• x11vnc with -threads -pointer_mode 4 -norepeat:
  • -threads → parallel I/O threads, less input lag.
  • -pointer_mode 4 → smoother mouse transmission than the default (1).
  • -norepeat → prevents duplicate keyboard auto-repeat in-game.
• -nodpms -nofbpm -nowf -nowcr → power saving and rate limiting disabled so nothing stutters after idle.

For slow networks (e.g. remote via the internet instead of LAN), enable compression in the .env:

X11VNC_EXTRA=-threads -pointer_mode 4 -norepeat -tight -compresslevel 6 -quality 7

Why Mouselook Doesn’t Work Properly

VNC transmits absolute mouse coordinates (“move cursor to position X/Y”). Minecraft, like any FPS-style game, needs relative mouse movement and re-centers the cursor to the middle of the screen every frame (noVNC issue #1493). That is why the camera cannot be turned meaningfully via VNC.

For menus, buttons, chat, inventory and plain AFK on a farm this does not matter. If you really want to play remotely, you need a different protocol (Sunshine/Moonlight instead of VNC) — not covered by this architecture.

---

API

Method	Path	Description
GET	/api/status	Status of display, VNC and Minecraft.
POST	/api/mc/start	Starts Prism Launcher.
POST	/api/mc/stop	Stops Prism + Minecraft.

Example:

curl -X POST http://localhost:8080/api/mc/start

---

Developing the Dashboard

For Vue development without rebuilding every time:

cd web
npm install
npm run dev    # → http://localhost:5173 (proxies /api + /websockify to :8080)

For the dev dashboard to work, the container must be running (docker compose up -d) so that the VNC stream and the API are reachable.

---

Performance Notes

• Minecraft renders inside the container via llvmpipe (CPU software OpenGL). Perfectly adequate for AFK farms (~1–2 CPU cores), but no smooth PVP.
• shm_size: 1gb is set so that OpenGL has enough shared memory.
• If a GPU is available, you can pass through /dev/dri (commented out in docker-compose.yml). MC then uses hardware rendering.

---

Project Structure

CTmine-client/
├── Dockerfile                # Multi-stage: Vue build + runtime
├── docker-compose.yml
├── .env.example
├── docs/
│   └── logo.svg              # Project logo (README header)
├── docker/
│   ├── entrypoint.sh         # PUID/PGID, /config, Xvfb/x11vnc config generation
│   ├── bootstrap-prism.sh    # Copies Prism into the volume on first start
│   ├── supervisor.conf       # Process manager for all services
│   ├── nginx.conf            # Dashboard + /api + /websockify proxy
│   └── mc-api/               # Node status API (no external dependencies)
│       ├── server.js
│       └── package.json
└── web/                      # Vite + Vue 3 + TypeScript dashboard
    ├── package.json · vite.config.ts · tsconfig.json
    └── src/
        ├── App.vue · main.ts · api.ts · types.ts
        ├── styles/main.css
        └── components/
            ├── VncViewer.vue     # noVNC integration
            ├── ControlPanel.vue  # MC start/stop, quick-start guide
            └── StatusBar.vue     # Status indicators

---

Security

This dashboard is built for trusted local networks — not for the public internet. Please note:

• Without VNC_PASSWORD the VNC stream is unprotected. Anyone who can reach the web port can see the screen and send input. Set a password as soon as other devices are on the network.
• Control API without login: /api/mc/start and /api/mc/stop are freely reachable (strangers on the LAN can kill your farm). The VNC WebSocket, however, is restricted to same-origin — foreign web pages in your browser cannot open a connection.
• config/prism/accounts.json contains your Microsoft refresh token in plain text. The folder is never committed to the repository (config/ is gitignored), but: anyone with read access to ./config or to the open dashboard effectively has your Minecraft account. Keep this in mind when sharing backups or support zip files.
• For internet access: only behind a reverse proxy with auth (e.g. OAuth proxy / basic auth + TLS).

---

Known Limitations

• Sound is not configured in the MVP (irrelevant for AFK farms).
• First login is interactive: the Microsoft login has to be done once in the VNC window via device code. Afterwards it persists.
• EULA/terms of service: this project only provides the infrastructure. You are responsible for complying with the Mojang/Minecraft terms of service and the rules of your target server.

---

License

MIT — see LICENSE if included. Minecraft is the property of Mojang/Microsoft; this project is not officially affiliated with them.