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.
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, and the two Atlas jars: atlas-paper.jar for the shards, atlas-velocity.jar for the proxy.
Most panels do not offer Java 25 or a pinned Paper 26.2 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

Generate the world once, then copy it to every server

This is the step with no error message, and the one that looks like a bug in Atlas when you skip it.Chunk decoration is not a pure function of the seed (PaperMC/Paper#14125). Two servers generating “the same” world from the same seed disagree about where the trees are, and you see it at the border as a seam where terrain does not line up.So generate once, locally or on one of the servers: boot Paper, pre-generate out to the edge of the grid (4096 by 2048 blocks for this layout), stop it, then upload that one world folder to both shards and the hub over SFTP.
server.properties
Every shard uses the same level-name, and it must match shard.world below. Leave server-port to the panel.After the copy each shard keeps its own copy, and what players build in region 0 lives only on region 0’s server. That is the point, and it is also why disk cost multiplies by the number of shards — see sizing.
2

Start the proxy once to get a forwarding secret

Install Velocity on the proxy server, start it, 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
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.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

Set up the hub

The hub is a plain Paper server. It gets the world copy and 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.Name it hub and the proxy finds it. If you call it something else, set proxy.hub to match.
6

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:
7

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.
8

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. 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, and copy the same world folder to them. 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.

​
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.
The copy is the constraint, not the grid. Every shard holds a full copy of the whole world, so disk is world size times shard count — and more shards does not divide the world up, it multiplies it. A 50,000 radius world at 4 shards is somewhere north of half a terabyte of panel storage, plus pre-generating 39 million chunks once and uploading the result four times.
Splitting into more regions does not help this: 4x4 at the same radius is the same 39 million chunks, copied sixteen times instead of four. What more regions buys is simulation headroom — more players and more redstone spread over more CPUs — not less disk. So size the world to what you will actually copy. A 5,000 to 10,000 radius is a large survival map, pre-generates in hours rather than days, and fits comfortably on rented storage. Push past that and the pre-generate-and-copy step becomes the whole project.
Atlas requires the copy because two servers generating the same seed disagree about decoration, and the seam shows at the border. If you are planning something much larger than the table above, ask before you buy the storage: what has to be identical is the ground where two shards can both show you the same place, which is a corridor along each border rather than the whole map — but Atlas does not currently do anything to help you generate only that, and the tested path is the full copy.

​
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.