> ## Documentation Index
> Fetch the complete documentation index at: https://nexohub.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Moving an existing network

> Getting three backends that each have their own plugins/Nexo/ down to one set of files.

The [quickstart](/quickstart) has you run `/nexohub adopt lobby`: you name a backend, it
sends its own `plugins/Nexo/` up, and that becomes `_shared/`. That is the whole job when
you have one backend, or when the others are copies of it.

A network that grew a server at a time is not that. It has three folders that have
drifted apart, and naming one of them decides what happens to the other two.

So the command is the easy part, and this page is the rest of it: choosing which backend
to name, and what to do about the ways the others differ from it.

## Before you start

Install both plugins the normal way first. Adoption needs the bridge running on the
backend you are adopting from, and it needs to know its own name.

<Steps>
  <Step title="Install NexoHub on the proxy">
    Drop the proxy jar in, start it, copy the generated secret, and set
    `http.public_address`. Leave `nexo-data/` empty; you are about to fill it.
  </Step>

  <Step title="Install the bridge on every backend">
    `NexoHubBridge.jar` next to Nexo, `hub.address` and `hub.secret` filled in,
    `server_name: auto`.

    `Pack.server.type: HUB` in each backend's `plugins/Nexo/settings.yml` is written by
    the bridge on its first start. The bridge also preserves `Pack.server` locally on
    every push, so this one setting never travels between servers.
  </Step>

  <Step title="Take a copy of every backend's plugins/Nexo/">
    Not optional. Once you adopt and push, each backend's files are overwritten by the
    hub's, and anything that lived only on one server and never made it into
    `nexo-data/` is gone from that server.

    Inside the trees the hub owns, a file it does not have is removed, so a backend
    cannot keep something the rest of the network lost. Outside them nothing is touched.
    A file that exists on two backends with different contents keeps the hub's copy.
  </Step>
</Steps>

## Choosing which backend to promote

Pick the backend whose files are closest to what every server should have. Everything you
get from it is one less thing to sort out afterwards.

That is usually the server with the most items and glyphs on it, so your survival or
lobby server rather than a minigame server that was set up from a trimmed copy.

Before you decide, compare them. If you can get the folders onto one machine:

```bash theme={null}
diff -qr lobby/plugins/Nexo pvp/plugins/Nexo
```

Then sort what comes back into four piles. It is worth doing this on paper before you
touch anything:

| The difference is | Where it goes |
| - | - |
| something every server should have had | `_shared/`, so promote the backend that has it |
| genuinely per-server, like a different `settings.yml` value | `servers/<name>/` afterwards |
| the same on several servers but not all | `groups/<name>/` afterwards, see [managing your files](/guides/managing-files#groups) |
| generated by Nexo or another plugin | nowhere; it is rebuilt |

That last pile is bigger than people expect. `pack/pack.zip`, everything under
`pack/external_packs/`, `.assetCache/` and `.deobfCachedPacks/` are all output. Two
backends differing there means nothing at all.

## Adopting

On the proxy:

```
/nexohub adopt lobby
```

```
[NexoHub] Asked lobby for its plugins/Nexo/ folder.
[NexoHub] Watch this console. What it leaves under pack/external_packs/ is listed there by name.
```

On that backend:

```
[NexoHubBridge] Sending 118 file(s), 2412 KiB, to the hub as 'lobby'.
[NexoHubBridge] The hub took these files; they are what the whole network builds from now.
```

And on the proxy:

```
[nexohub] Adopted 118 file(s) from lobby into _shared/.
[nexohub] lobby kept 4 entr(y/ies) in pack/external_packs/, which adoption never carries:
[nexohub]   DefaultPack_5b8ebdadb1.zip: Nexo downloads this itself, on every backend
[nexohub]   ShizuArt_Tavern_Furniture.zip: nothing on that backend says it wrote this, so it looks like yours
[nexohub]   _hub-betterhud-abcdef12: the hub put it here, and it is replaced on every push
[nexohub]   betterhud.zip: BetterHud writes it, on every backend that runs it
[nexohub] 1 of those are not accounted for by any plugin there. Put them in
          nexo-data/_shared/pack/external_packs/ if the whole network should have them.
```

The hub then pushes, so every other backend receives those files immediately.

<Note>
  If a player is connected the request arrives at once, otherwise the backend picks it up
  on its next poll.

  The one case that needs a player is a backend on `server_name: auto` that has never had
  one. It does not know its own name yet, so it cannot be adopted from until someone joins.
</Note>

### What does not come up

Only the files you wrote yourself come up. Left behind on purpose:

* `pack/pack.zip`, the built pack
* everything under `pack/external_packs/`, which your plugins rebuild anyway
* hidden files and folders, so `.assetCache/` and `.deobfCachedPacks/` stay put
* editor backups ending in `~`
* anything over 64 MB

`external_packs/` is the one of these worth reading rather than skimming, because it is
not all generated output. A pack you bought and dropped straight onto a backend lives
there too, and adoption leaves it exactly where a plugin's own output is left. That is
deliberate: promoting one backend's copy of that folder would freeze its build into what
every server then rebuilds from.

So adoption names what it left, on both consoles, and separates the entries a plugin on
that backend claims from the ones nothing claims. The unclaimed ones are yours. Upload
them once to `nexo-data/_shared/pack/external_packs/` and every backend has them from
then on. A `.zip` works there as well as an unpacked folder.

### Why it asks first

The hub refuses an adoption nobody asked for. Every backend already holds the secret, so
without that check any one of them could overwrite your files at any time.

The window a `/nexohub adopt` opens lasts five minutes and works once. If you see one of
these, that is what happened:

```
no adoption was requested; run /nexohub adopt lobby on the proxy first
that request expired; run /nexohub adopt lobby again
```

### If `_shared/` is not empty

Adopting writes the backend's files over `_shared/` without clearing it first, so a file
that exists there and not on the backend stays. That is fine when you are re-adopting
after a change, and misleading when you are starting over.

A snapshot is taken before anything is overwritten, so if you want a clean slate, delete
`_shared/` over SFTP first and adopt into the empty folder. `/nexohub history` still has
the old one.

## Afterwards

<Steps>
  <Step title="Check it parses">
    ```
    /nexohub validate
    ```

    A hand-edited `plugins/Nexo/` that has been in production for a year is a good place
    to find a file nobody has loaded since it was written.
  </Step>

  <Step title="Put the differences back">
    Work through the piles from earlier. Per-server files go in `servers/<name>/`, files
    several servers share go in a group, and everything else you leave alone.

    Save them all in one go if you can; the hub debounces, so one upload means one
    reload rather than one per file.
  </Step>

  <Step title="Look at every backend">
    ```
    /nexohub status
    ```

    Every server should be `in sync` on the same bundle, and the layer names next to each
    one should be the overrides you meant to give it. Empty servers included, since they
    report on their poll.
  </Step>

  <Step title="Run the full check">
    ```
    /nexohub doctor
    ```

    This is the moment it earns its keep. It will tell you whether players can actually
    reach `public_address`, whether any backend failed its reload, and whether your
    backends are on Nexo or Minecraft versions that will build different packs. Version
    drift is common on a network that grew one server at a time, and it is close to
    impossible to attribute from the outside.
  </Step>

  <Step title="Join a server and switch">
    Download the pack once, hop between two servers, and watch for a second download.
    One download and the migration is done. See
    [troubleshooting](/guides/troubleshooting#players-re-download-when-switching-servers)
    if there is a second.
  </Step>
</Steps>

## If it goes wrong

The state before the adopt is in `/nexohub history`, under `before adopting <server>`.

```
/nexohub rollback 1769508900000-77c1a2e5
```

That puts `nexo-data/` back and pushes it. See
[not breaking your network](/guides/safety#going-back) for what a rollback does to files
added since.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.