# PixelServers Agent

This small program turns your own PC into a Minecraft server host. It downloads
and runs Paper, Purpur, Folia, Fabric, Quilt, Forge, NeoForge or Vanilla servers,
and lets the PixelServers web panel control them.

Server files and worlds stay in the `PixelServers` folder in your home directory.
The panel talks to the helper on your own machine only
(`http://127.0.0.1:41815`). Minecraft server addresses are localhost and the
host's local-network IPv4 addresses; PixelServers does not make the panel or
server internet-accessible. If you set up Playit, Minecraft player traffic is
relayed through Playit's service.

The helper is `pixelservers-agent.mjs` and it has no npm dependencies — only
Node.js built-ins.

## Server versions and add-ons

The server type selector loads releases from the selected server's upstream
metadata (Mojang, PaperMC, Purpur, Fabric, Quilt, Forge, or NeoForge). Velocity
is a proxy rather than a Minecraft game server, so its selector lists upstream
Velocity software releases instead of game versions. A server is created only
after the agent resolves the exact selected loader/version pair. If upstream no
longer supports that pair, creation fails with an error instead of silently
switching to another release.

The server panel shows a Plugins tab for plugin servers and a Mods tab for
modded servers, and hides content installation for Vanilla. Modrinth results
are filtered for the server's loader and Minecraft version. The agent rechecks
the project type, loader, and game version before downloading its JAR.
Vanilla server downloads are verified against Mojang's published file size and
SHA-1 checksum before they are installed.

## Server files

The Files tab is rooted in the selected server's own folder. It supports nested
browsing, file upload/download, editing UTF-8 text files up to 1 MiB, and
deleting files or folders after confirmation. Uploads are limited to 32 MiB.
Paths cannot traverse outside the server folder, and symbolic links are not
followed by file operations. Files and worlds remain on this PC.

## Windows quick start

Download and open `PixelServersSetup.exe` from the PixelServers website. On
first run, it downloads portable Node.js and Java 21 runtimes if needed,
prepares Java 25 for Minecraft releases that require it, then starts the helper
in the background. Return to the website; the Servers page will connect
automatically. When updating an already-running helper, stop the existing
`node.exe` process from Task Manager after stopping any running Minecraft
servers, then run the updated setup. The installer detects an old helper and
explains this if you forget.

## Manual start (macOS / Linux)

Install Node.js 18 or newer and Java 21; Java 25 is needed for the latest
Minecraft releases. Then run `./start-unix.sh` (or `node pixelservers-agent.mjs`).

The helper must stay running while the server is online. The agent uses
low-pause garbage collection flags so games, browsers and work apps stay
responsive.

Open the PixelServers control panel on the host PC (for a local development
website, use `http://localhost:5173`) and go to the Dashboard. It will connect
automatically. The website binds to localhost; other devices use the host PC's
local IP in Minecraft, not the website URL.

## Letting friends join

- **Same house / Wi-Fi:** friends use the local IPv4 address shown on the
  server page, e.g. `192.168.1.24:25565`.

The address works only on the same local network. Connecting from outside that
network requires additional networking setup.

## Where things are stored

```
~/PixelServers/
  servers/     one folder per server (worlds, plugins, mods, configs)
  backups/     zipped snapshots you create from the panel
  cache/       downloaded loader metadata and server jars
  state.json   your server list
```

If you hosted with the older `HomeHost` build, your data folder is renamed to
`PixelServers` automatically on first run (the runtime folder under
`%LOCALAPPDATA%\HomeHost` is re-created as `%LOCALAPPDATA%\PixelServers`).

## Change the port

```
PIXELSERVERS_PORT=41999 node pixelservers-agent.mjs
```

## Environment variables

| Variable                    | Purpose                                                          |
| --------------------------- | ---------------------------------------------------------------- |
| `PIXELSERVERS_HOME`         | Data folder (defaults to `~/PixelServers`).                      |
| `PIXELSERVERS_PORT`         | Local API port (defaults to `41815`).                            |
| `PIXELSERVERS_JAVA_<major>` | Path to a specific Java executable, e.g. `PIXELSERVERS_JAVA_25`. |

## Stop / uninstall

Stop the `node.exe` process from Windows Task Manager to shut down the helper.
Delete the `PixelServers` folder in your home directory and
`%LOCALAPPDATA%\PixelServers` to remove server data and the downloaded runtime.