Skip to Content

Get started

Setup wizard

Give a fresh instance its domain, connect the GitHub App, and sign in as the owner.

Setup runs in a fixed order: the domain first, then the GitHub App on that domain, then your owner account. GitHub sends you back to the instance’s final https:// address after sign-in, so that address has to exist before the App does.

1. Enter the setup code

Open the setup page the installer printed, http://<server>:5123/, and enter the Setup code from the same summary (nxs_…). Lost it? Run sudo nexul status on the server; the page has it with a copy button. Each step shows where you are, such as “Step 2 of 3”.

The code proves you installed the server, so a stranger who finds the port cannot take over the instance. A correct code unlocks setup in this browser for an hour. The server writes a new code each time it starts, each one good for a day, and setup closes for good once someone has signed in.

2. Give Nexul a domain

Pick how traffic reaches Nexul. There is no skip, because GitHub sign-in needs the domain. The three ways are equals: Cloudflare is one way in, not a requirement, and computers for your agents pair without it (see the Welcome wizard after the owner wizard).

  • Cloudflare tunnel: no open ports. Paste a Cloudflare API token (see the permissions it needs), pick the account that owns your domain, deploy the tunnel, then choose the subdomain and zone. Cloudflare issues the certificate.
  • Reverse proxy: type the domain. The page shows the A (and AAAA) record to create at your DNS provider and waits until the domain resolves to this server. Nexul then runs Traefik on ports 80 and 443 with a Let’s Encrypt certificate. Both ports must be reachable from the internet.
  • I already have HTTPS: your own proxy already serves an https:// address that forwards to http://<server>:5123. Type it in.

Each path ends with Nexul checking that the address answers over HTTPS, then saving it as the instance URL.

On a Mac or Windows install this step is skipped and the instance stays on http://localhost:5123.

3. Continue on your domain

The page links to your new address. The link carries the setup code, so you land straight on the next step.

4. Connect a GitHub App

Two ways, switched at the top of the step:

  • Create on GitHub (the default): Create App on GitHub registers the GitHub App with the addresses and permissions filled in, and GitHub hands its credentials straight back.

  • Use an existing App: for an App you registered yourself. The page shows the Homepage URL and Callback URL to register on it, each with a copy button, and the repository permissions to give it (Contents read; Pull requests and Webhooks read and write), then asks for:

  • GitHub OAuth client ID and GitHub OAuth client secret, from the App’s page.

  • GitHub App slug, the name after github.com/apps/ in the App’s URL.

Click Verify. Three checks run: Instance URL reaches this server, App slug resolves, and Client secret accepted. When all three pass, Set up instance sends you to GitHub to sign in as the first user.

Got a value wrong? Until someone has signed in, open /setup on your domain to correct it.

5. Owner wizard

The first person to sign in becomes the workspace owner and walks through three steps:

  1. Introduce yourself: the name and avatar others see. The GitHub ones are the default.
  2. Set up your workspace: name it. A new workspace has no projects yet.
  3. Connect your tools: the same list as Settings → Connectors. Cloudflare is optional here: connect it only if you want Nexul to manage your domain, exposures and DNS records. It already shows as connected if you used the tunnel.

Workspace ready confirms the workspace, and the Welcome wizard takes over with what’s yours to set up: Connect GitHub and Your computer. It opens on the first of them not done yet. Either can wait: Skip for now moves on, and Finish later leaves the wizard. Whatever is left stays under Welcome in your account menu, with a red dot until it’s done.

Your computer is where agents run: run its one command on that computer, the same as Settings → Computers. It needs no Cloudflare and no domain. The three checks, Computer connected, T3 Code found and Paired, turn green, then Set up sets up the computer. See paired computers.

A new workspace has no projects, so the Welcome wizard ends with Create your first project, which opens the project wizard.

Everyone who signs in after you gets the Welcome wizard too: their name and avatar first, then the steps their roles give them.

If something goes wrong

  • “That code is wrong or has expired”: the server restarted and wrote a new code, or yours is over a day old. Run sudo nexul status for the current one, or sudo systemctl restart nexul-server for a fresh one.
  • “Too many wrong codes from this address”: wait a few minutes and try again.
  • “Setup is already done on this instance”: someone has signed in. Sign in instead.
  • The domain check never passes: for the reverse proxy, check that the DNS record points at this server and that ports 80 and 443 are open. For your own proxy, check it forwards to the web port.
Edit this page