Skip to main content
This page builds a two region network on a Pterodactyl-style panel, because that is where most Atlas networks run. One border is enough to see everything the system does, at half the servers to learn on. Going to four is one extra step once it works, and sizing it for a real SMP is one number. Everything here works the same on a plain VPS or on one machine — the only panel-specific part is where addresses and ports come from.
Already running a server with players? Moving an existing server onto Atlas keeps the world and everybody’s things — it uses the same proxy and hub set up here.
Two regions side by side, region 0 covering x -2048 to 0 and region 1 covering x 0 to 2048, with spawn on the border between themTwo regions side by side, region 0 covering x -2048 to 0 and region 1 covering x 0 to 2048, with spawn on the border between them

What you are about to build. Two regions side by side, one border down the middle.

On a panel that is four servers you rent — two shards, a hub, a proxy — plus MongoDB and Redis, which are not Minecraft servers and usually come from somewhere else.
If you have Docker and the repo, docker-test/setup.sh builds this exact network locally and prints the command to start it. Every value on this page comes from that harness, which is run against each change, so these are settings known to boot.

Before you start

Roughly 6 GB of RAM across the four servers, your licence key, and the Atlas jars: atlas-paper.jar for the shards, atlas-velocity.jar for the proxy’s plugin, and atlas-proxy.jar, the proxy itself.
Most panels do not offer Java 25 or a Paper 26.2 or 26.3 egg yet, and neither is something you can work around from inside the container. Confirm both with your host first — a mismatch is a startup crash, not a degradation.

On a panel specifically

Three things work differently to a VPS, and all three cause the same confused hour if nobody says them:
Each server gets an allocation — an IP and port the panel assigns. You do not choose server-port; the panel sets it. What you do choose is shard.address, and it must be the allocation the proxy can dial, which on most panels is the public one.
Atlas reads settings from the environment and from config.yml, and the file wins. That is deliberate, but it means an operator who edits a panel variable and sees nothing change has no way to find out why. Put your settings in plugins/atlas/config.yml and treat the panel variables as unused.
Every server you rent gets its own public address, and no firewall you control. So the forwarding secret is doing all of the security work. Read Security before anyone else knows your IP.

Build it

1

Give both shards the same seed

Nothing is copied between servers. Each shard runs the same seed and generates only its own region; the ground either side of the border is shared through MongoDB, which is what keeps the border from showing a seam. How that works is in Same seed, no world copy.
server.properties
Every shard uses the same level-seed and the same level-name, and level-name must match shard.world below. Leave server-port to the panel.What players build in region 0 lives only on region 0’s server. That is the point.
2

Start the proxy once to get a forwarding secret

Use atlas-proxy.jar as the proxy server’s jar — it is Velocity, so a Velocity egg runs it — then start it and stop it. It writes velocity.toml and a forwarding.secret. You need that secret before the shards can be configured, which is why the proxy comes first.
velocity.toml
Both switches are off in a fresh velocity.toml; without them every border is a loading screen. See The proxy.Only the hub is listed. The shards register themselves out of MongoDB from their shard.address, so listing them here is neither needed nor wanted. Clear [forced-hosts] as well: a forced host naming a server that does not exist fails Velocity’s own validation and the proxy will not start.
3

Configure the proxy plugin

atlas-velocity.jar into the proxy’s plugins/, then:
plugins/atlas/config.yml
geo is only a name for this network. Any short word, the same on every box.
4

Configure the two shards

Each shard gets atlas-paper.jar in plugins/, the file below with region and address changed, and the forwarding secret in paper-global.yml.
address is that server’s own allocation — the one the proxy dials — and setting it is the whole of self-registration. border-chunks is what shares the ground along the border; it is off unless you turn it on.Then on both shards and the hub:
config/paper-global.yml
The grid block must be identical on both shards and the proxy. A box that disagrees routes players to a server that does not own where they are standing, and nothing detects it for you. Leaving all three at their defaults is the safest way to keep them in step.
5

Add your licence key

The same key goes into plugins/atlas/config.yml on both shards and the proxy:
plugins/atlas/config.yml
Without a valid key a shard will not start and the proxy turns everyone away — the console says which. If the licence server cannot be reached, a server that has verified before keeps running for up to two days while it retries. Licence has the details.
6

Set up the hub

The hub is a plain Paper server with the same paper-global.yml forwarding block and no Atlas plugin — it owns no region, so there is nothing for the plugin to do there. It needs no copy of the shards’ world; any world will do.Name it hub and the proxy finds it. If you call it something else, set proxy.hub to match.
7

Start in order

MongoDB and Redis first, then the shards, then the hub, then the proxy.Nothing breaks if you get this wrong — a shard with no database retries, and a proxy with no shards sends everyone to the hub — but starting bottom-up means the first error you read is the real one rather than a consequence of it.Watch each shard’s console for the region it claims. A misspelled setting is named rather than ignored:
8

Pre-generate each region on its own shard

Install Chunky on each shard and run /shard pregen there. It prints the commands that generate exactly that shard’s square:
Each shard publishes its side of the border as it goes. You can skip this and let players generate as they explore, but then the first person to walk a stretch of border is the one who pays for generating it.
9

Check it worked

Join through the proxy, not through a shard, and run:
Two live owners and no dash means the shards registered themselves and the proxy can see both. A dash is a region nobody is serving./shard on its own then tells you which region you are in and how far you are from the nearest edge.
10

Walk across the border

Spawn at 0,0 sits exactly on the border, in region 1 — the square starting at a line owns it. So walk west, into negative x, and you cross within a few blocks.Turn on /shard walls first and the boundary is drawn as a particle curtain. /shard bar puts your shard, your ping and the distance to the next border in a boss bar.What you should see: no loading screen, your inventory intact, and the ground on the far side already drawn before you got there. A loading screen means the proxy is not keeping the client’s world — its console names the setting. What you should not see is a disconnect — if you get one, the forwarding secret is wrong on the shard you were walking into.

Going to four regions

Rent one more shard, change one number on every box, and restart the network.
Set the new servers to region: 2 and region: 3, give each its address, the same seed and border-chunks: true, then run /shard pregen on each — including the two you already had, because their squares just changed. Region numbering is left to right then top to bottom from the north-west corner, so the layout becomes: Spawn at 0,0 moves from region 1 to region 3, because regions-z changing moves where the origin sits.
This is a full restart, not a rolling one. Changing the grid changes which region a standing player belongs to, so every shard and the proxy must come back with the new numbers together. Do it with nobody online.
One region busier than the rest? You do not have to change the whole grid: split just that one in half or in four, and give the new part its own server.

Sizing the world for a real SMP

A 2048 region is a tutorial. A real SMP is tens of thousands of blocks across, and the grid handles that fine — region-size is the only number you change.
region-size must be at least 256 and a multiple of 16. There is no upper limit in Atlas. With border chunks each shard generates and stores only its own square plus a thin corridor of its neighbours’, so more regions divides the world up: a 4x4 is the same map in sixteen pieces, each pre-generated in parallel on its own server. More regions also buys simulation headroom — more players and more redstone over more CPUs.
If you leave border-chunks off and copy one world folder to every shard instead, every shard holds the whole map: about 224 GB each at a 50,000 radius, and more shards multiplies it rather than dividing it. That path still works and is the conservative one while border chunks are new.

When it does not work

More in Troubleshooting.

Next

Security

Read this before anyone else knows your IP. On a panel the forwarding secret is the only thing protecting the shards.

Panel and VPS hosting

Self-registration in full, and spreading the same network across two or three providers.

Grid and ownership

Why the border falls where it does, and what stops two servers both owning you.

Configuration

Every setting, and which ones must match across the network.