How to use a truetick server as a backend for an external Velocity proxy

If your Velocity proxy runs somewhere we don't control — a friend's box, a different host entirely — you can still put a truetick server behind it as a backend. This is different from server networks, where the proxy is also a truetick server: here the proxy is external, and truetick's job is just to expose one backend server at a fixed address the external proxy can dial.

This is the flow the deterministic external-backend port was built to support. Read the restart note in Step 4 before you start — it's the one step that looks optional and isn't.

Requirements: the truetick server must be on the Flat plan (an external proxy can't wake a sleeping backend) and running Paper or Purpur (Velocity's forwarding protocol needs a Paper-family server; Vanilla/Forge/Fabric don't support it).

Step 1: enable External backend on the truetick server

Open the truetick server → Settings → External backend. If the toggle is disabled, the panel tells you why (wrong plan, or not a Paper/Purpur server).

Turn it on. The panel shows a dial address like 203.0.113.9:33000 — this is the exact, fixed <box-ip>:<port> the external proxy will connect to. Copy it; you'll need it in Step 4.

This address is deterministic: it doesn't depend on the server's hostname or which node it's on, and it won't change on its own. That's the whole point — the external proxy dials the port directly, so nothing on our side needs to know or trust the proxy's own configuration.

Step 2: server.properties — turn off the backend's own auth

On the truetick server, open Files → server.properties and set:

online-mode=false

The external proxy does the real Mojang authentication and forwards the verified identity to the backend; the backend must not also try to authenticate the connection itself, or it rejects the forwarded session.

Step 3: paper-global.yml — enable Velocity forwarding and set the secret

Still in Files, open config/paper-global.yml and set, under proxies.velocity:

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "paste the EXTERNAL proxy's forwarding.secret here"

The secret here is not anything truetick generates — it's the forwarding.secret file that already exists on the external proxy's own install (Velocity creates it automatically the first time it starts). Copy that exact value in. If it doesn't match byte-for-byte, the backend rejects the proxy's forwarded connections.

online-mode: true here keeps real online UUIDs — it's a different setting from server.properties online-mode=false in Step 2, not a contradiction of it: the backend stops doing its own Mojang auth (Step 2), while this setting tells the backend to trust and use the online UUID that the proxy forwarded instead of generating an offline one.

Restart the truetick server so both files take effect.

Step 4: point the external proxy at the backend — and restart it fully

On the external proxy's velocity.toml (not on truetick — this file lives on the other host):

player-info-forwarding-mode = "modern"

[servers]
truetick = "203.0.113.9:33000"   # the dial address from Step 1

try = ["truetick"]

Use the exact <box-ip>:<port> you copied in Step 1. try is what tells Velocity which server a player lands on first — add the name you used in [servers].

After editing velocity.toml, do a full restart of the external proxy rather than a hot reload. Some proxies don't reliably apply server-list or forwarding changes without a restart. Stop the proxy process and start it again (not /reload, not /velocity reload) after any velocity.toml change.

Troubleshooting

• Player lands on the wrong server, or nothing changes after editing velocity.toml — check whether you used /reload instead of a full restart. See the note above; stop and start the proxy process.
• "This server requires you to connect with Velocity" — the backend's forwarding isn't enabled, or the secret doesn't match. Recheck Step 3: proxies.velocity.enabled: true and secret: set to the external proxy's forwarding.secret, then restart the backend.
• Backend server is online-mode! — server.properties still has online-mode=true on the truetick backend. Set it to false (Step 2) and restart.
• Client gets kicked with a version message, or can't connect at all — the client's Minecraft version doesn't match the backend's. Either match versions, or install ViaVersion on the external proxy.
• "Unable to connect to server" / "Connection reset" in the proxy console — the proxy can't reach <box-ip>:<port> at all. Double-check you copied the exact dial address from Step 1 (not an old hostname, not the truetick server's regular connect address), and confirm the truetick server is actually running — a stopped Flat server has nothing listening on that port.
• Wrong port, or "it worked yesterday, not today" — the dial address is now deterministic and doesn't change; if it doesn't match what's in velocity.toml, re-copy it from Settings rather than reusing an old value.

Good to know

• The port is public. Unlike a truetick-to-truetick server network, this address is reachable from the internet — that's required for an external host to dial in. The forwarding secret is the only thing gating access: anyone who has both the address and the secret can connect as the proxy. Keep the secret private the same way you'd keep any credential private.
• Flat only, for now. A sleeping Metered server can't be woken by a proxy we don't control, so External backend is gated to Flat.
• You configure both ends. Today this is manual on both sides — the truetick backend via Files (Steps 2–3), the external proxy via its own velocity.toml (Step 4). We plan to automate the backend side later; until then, the panel shows you the exact values.