Quickstart

Orbit is built to be run by your coding agent. This page is written for both of you. Your agent reads it and does the work. You read it to know what happens, what your agent needs from you, and how to check the result. At the end you have a Gateway, one development Node, and a Project at https://hello.test.

Hand this page to your agent

Open this page in your agent from the menu at the top, or paste its link into the agent you already use with a prompt like this:

Read https://orbit.nckrtl.com/docs/quickstart and guide me through it. I have two fresh Ubuntu 26.04 machines. You can reach them as root@<GATEWAY_IP> and root@<NODE_IP>. Ask me when you need something only I can do.

Your agent needs a shell that can reach both machines over SSH. Your own laptop is fine. Every command below names the machine and the account it runs on.

Your part

Two fresh Ubuntu 26.04 machines that you reach over SSH as root. One becomes the Gateway, the other a development Node. Both need outbound access to package sources and GitHub.
Open UDP port 51820 to the Gateway machine in the provider firewall. WireGuard uses it.
Keep the provider console open for both machines. Orbit closes public SSH on a Node once its role is active, and one host fingerprint has to come from the console, not from the network.
The WireGuard range 10.44.0.0/24 must be free on your network. If it is in use, tell your agent which range to use instead.

Each step marks the moments that need you with You:.

Your agent’s part

Everything else. Before you run anything:

Confirm with the user which machine becomes the Gateway and which becomes the Node. The machine that runs you is usually neither.
Check for an existing installation on the Gateway machine with id orbit and systemctl is-active wg-quick@orbit. If either succeeds, reuse that installation. Do not bootstrap over it.
Run every command on the machine and account named in its title.
If a command fails, read the error code, fix the cause, and run the same command again. Do not rename records or add a machine under a new name to get past a failure.
Never skip certificate verification. No --insecure, no disabled TLS checks.
Keep keys, tokens, and .env values out of the chat and out of every repository.

Check each checkpoint before you continue to the next step.

Prepare the Gateway machine

Install the packages Orbit needs and create the orbit account that owns the Gateway:

Gateway machine · root

apt-get update
apt-get install --yes git curl unzip openssl sqlite3 composer sudo gnupg \
  openssh-server ca-certificates iproute2 ufw wireguard-tools dnsmasq \
  php8.5-cli php8.5-fpm php8.5-curl php8.5-mbstring php8.5-sqlite3 php8.5-xml
adduser --disabled-password --gecos '' orbit
printf 'orbit ALL=(ALL) NOPASSWD:ALL\n' > /etc/sudoers.d/orbit
chmod 0440 /etc/sudoers.d/orbit

The orbit account has passwordless sudo because bootstrap configures Caddy, WireGuard, dnsmasq, and the firewall. The rest of the Gateway steps run as orbit, for example through sudo -iu orbit or ssh orbit@<GATEWAY_IP> after you add a key for it.Checkpoint: sudo -iu orbit whoami prints orbit.

Install Orbit

Clone the repository under /home/orbit/orbit and install the CLI and the Gateway:

Gateway machine · orbit

git clone https://github.com/nckrtl/orbit.git /home/orbit/orbit
cd /home/orbit/orbit
composer --working-dir=apps/cli install --prefer-dist --no-interaction
composer --working-dir=apps/cli check-platform-reqs
composer --working-dir=apps/gateway install --prefer-dist --no-interaction
composer --working-dir=apps/gateway check-platform-reqs
echo 'export PATH="/home/orbit/orbit/apps/cli:$PATH"' >> ~/.profile
export PATH="/home/orbit/orbit/apps/cli:$PATH"
orbit --version
git rev-parse HEAD

This installs the current main. When a release tag exists, check it out with git checkout --detach <TAG> before you run Composer. Record the commit from git rev-parse HEAD and report it to the user at the end; it belongs in every bug report.If a platform check fails, for example because the package source has no PHP 8.5, stop and report the error. Do not install with --ignore-platform-reqs.Configure the Gateway:

Gateway machine · orbit

cd /home/orbit/orbit/apps/gateway
cp .env.example .env

Set these values in .env and keep the rest as they are:

apps/gateway/.env

APP_ENV=production
APP_DEBUG=false
APP_URL=https://10.44.0.1
ORBIT_HOME=/home/orbit/.orbit
ORBIT_GATEWAY_CHECKOUT=/home/orbit/orbit/apps/gateway

APP_URL is the Gateway’s WireGuard address; change it if the user chose another range. ORBIT_GATEWAY_CHECKOUT points at apps/gateway, not at the repository root.Keep CACHE_STORE=file. The Gateway holds its locks in that cache store, and they must exclude other processes. It starts only with a file, redis, memcached, or dynamodb store; it has no cache tables for database, and array or null locks do not span processes. When a line is missing, the Gateway uses files for the cache, an in-memory session, and synchronous jobs.Create the state directory and the database:

Gateway machine · orbit

cd /home/orbit/orbit/apps/gateway
umask 077
mkdir -p /home/orbit/.orbit
touch /home/orbit/.orbit/gateway.sqlite
chmod 0700 /home/orbit/.orbit
chmod 0600 .env /home/orbit/.orbit/gateway.sqlite
php artisan key:generate --no-interaction
php artisan migrate --force

The application key encrypts stored secrets. It belongs in every backup together with the database; Update and recover a Gateway lists what a backup needs.Checkpoint: orbit --version prints a version and php artisan migrate --force reports its migrations without an error.

Bootstrap the Gateway

You: confirm that UDP port 51820 is open to the Gateway machine.Bootstrap with the public address that the Node will use to reach the Gateway:

Gateway machine · orbit

cd /home/orbit/orbit/apps/gateway
php artisan orbit:bootstrap '<GATEWAY_PUBLIC_HOST>' --no-interaction

Bootstrap creates the Gateway’s SSH key, WireGuard key, and root certificate authority. It registers the Gateway as the first Node with the gateway and vpn roles and starts the private HTTPS endpoint and DNS. It installs Caddy from the Caddy project’s own package source, not the Ubuntu archive, because Orbit renders directives the archive release does not know. Node provisioning describes the pinned key and the release floor. php artisan orbit:bootstrap --help lists the range, address, port, and DNS options. A failure names its step and an error code; fix the cause and run the same command again.Checkpoint: every service reports active, and caddy version reports 2.9.0 or newer:

Gateway machine · orbit

sudo systemctl is-active php8.5-fpm caddy wg-quick@orbit dnsmasq
caddy version

Use Orbit DNS on the Gateway

Nodes receive Orbit DNS automatically. The Gateway itself does not, so point its resolver at the Gateway’s WireGuard address. This lets the Gateway resolve hello.test later.

Gateway machine · orbit

sudo install -d /etc/systemd/resolved.conf.d
printf '[Resolve]\nDNS=10.44.0.1\nDomains=~.\n' | \
  sudo tee /etc/systemd/resolved.conf.d/orbit-gateway.conf >/dev/null
sudo ln -sfn /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf
sudo systemctl restart systemd-resolved

Orbit DNS forwards public names to upstream resolvers, so the machine keeps normal internet name resolution. See Private DNS.Checkpoint: both lookups return an address:

Gateway machine · orbit

getent ahostsv4 gateway.orbit
getent ahostsv4 github.com

Connect the CLI

Register the Gateway as a CLI profile. The CLI fetches the root certificate, checks it against the file bootstrap wrote, and installs it in the trust store, so it can ask for sudo.

Gateway machine · orbit

orbit gateway:add 10.44.0.1 --use --ca=/home/orbit/.orbit/ca/root.pem
orbit gateway:status
orbit node:list

The Gateway identifies callers by their WireGuard address, not by a token, and its own Node has authority over the whole fleet. Profiles live in ~/.orbit/config.json; the gateway family explains profiles and trust recovery.Checkpoint: gateway:status succeeds over HTTPS and node:list shows one Node, the Gateway.

Add a development Node

You: open the Node in the provider console, run ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub -E sha256, and give the SHA256: fingerprint to your agent. A fingerprint read over the network cannot prove which machine answered; the console can.Before the first connection to the Node, confirm that the machine on the network shows the same fingerprint:

Agent machine

ssh-keyscan -t ed25519 '<NODE_PUBLIC_HOST>' 2>/dev/null | ssh-keygen -lf -

The Gateway needs SSH access to the Node. Print the Gateway public key, then authorize it on the Node:

Gateway machine · orbit

cat /home/orbit/.orbit/ssh/id_ed25519.pub

Node machine · root

install -d -m 0700 /root/.ssh
echo '<GATEWAY_PUBLIC_KEY>' >> /root/.ssh/authorized_keys
chmod 0600 /root/.ssh/authorized_keys

Add the Node with the app-dev role and a development TLD. Generated hostnames use that TLD.

Gateway machine · orbit

orbit node:add dev '<NODE_PUBLIC_HOST>' \
  --role=app-dev \
  --tld=test \
  --host-key-fingerprint='SHA256:<FINGERPRINT>'
orbit node:list

The Gateway connects as root, creates the managed orbit user, joins the machine to WireGuard, and installs the role. Pass --user if the provider uses another bootstrap account. Once the role is active, public SSH on the Node closes and the Gateway reaches it over WireGuard only. That is expected; tell the user. Node provisioning lists the error codes.Checkpoint: node:list shows dev with an active app-dev role. Record its numeric ID.

Create the Project and its Instance

A Project records one repository. An Instance is a checkout of that Project on one Node, with its own hostname. This guide uses MDN’s public learning repository because its static page needs no dependencies, application key, or database. The user’s own application comes after this page. For a private repository, keep credentials out of the URL and set up Git access on the Gateway and the Node first.

Gateway machine · orbit

orbit project:create hello laravel-app https://github.com/mdn/learning-area.git \
  --default-branch=main --root=html/introduction-to-html/getting-started
orbit instance:create <PROJECT_ID> <NODE_ID> default

project:create returns the Project ID; use it with the Node ID from the previous step. Orbit clones the repository on the Node, publishes the Route, and prints the URL. The name default gives the Project its <project>.test hostname; any other name gives <name>.<project>.test.

Active means Orbit prepared the source, runtime, and Route. For a real application, composer install, an application key, and a database are the next step. The Applications guide explains that boundary.

Checkpoint: instance:create returns https://hello.test and the Instance is active. Record the instance ID.

Open the page

Resolve the hostname and fetch the page with the Orbit root certificate:

Gateway machine · orbit

getent ahostsv4 hello.test
curl --fail --cacert /home/orbit/.orbit/ca/root.pem https://hello.test

The first request can fail with HTTP 401 while Orbit wakes the Instance. Run the curl command again after a moment. See runtime wake.Then check the fleet:

Gateway machine · orbit

orbit doctor
orbit activity:list

Doctor compares each Node with what the Gateway expects and exits 1 on drift, without changing anything. Activity shows who ran what, including you.If DNS fails, check the WireGuard link and Private DNS. If HTTPS fails, check the hostname, the certificate, Caddy, and orbit node:show <NODE_ID>. If the page is wrong, check the branch and the web root.Checkpoint: the response contains This is my page and orbit doctor exits 0.

Report back

Tell the user:

The URL, https://hello.test, and the Project, Node, and Instance IDs.
The source commit from git rev-parse HEAD.
What their own machine needs to open the URL in a browser: a route to the private network, Orbit DNS, and the Gateway root certificate in its trust store. orbit gateway:add installs the certificate on any machine that runs the CLI. A Mac also needs a route to the Node; orbit dns:resolve configures only its resolver.
That orbit instance:destroy <INSTANCE_ID> removes the example when they are done. The Node stays.

Next steps

Bring your own application

Create an Instance from your repository, register an existing checkout, and finish the application setup.

Run a development server

Record Vite or a queue worker as a Process. Idle Processes hibernate and wake on the next request.

Attach a database

Ship to production

Clone a candidate into a production Instance, configure deploy steps, and deploy.

Work from another machine

Provision a Linux operator Node from the Gateway and grant it access with node:access:add.

Every command

The conventions shared by all families, and the family pages.

Start here

Applications

Fleet

Contributing

Solutions

Hand this page to your agent

Your part

Your agent’s part

Prepare the Gateway machine

Install Orbit

Bootstrap the Gateway

Use Orbit DNS on the Gateway

Connect the CLI

Add a development Node

Create the Project and its Instance

Open the page

Report back

Next steps

Bring your own application

Run a development server

Attach a database

Ship to production

Work from another machine

Every command

​Hand this page to your agent

​Your part

​Your agent’s part

Prepare the Gateway machine

Install Orbit

Bootstrap the Gateway

Use Orbit DNS on the Gateway

Connect the CLI

Add a development Node

Create the Project and its Instance

Open the page

​Report back

​Next steps

Bring your own application

Run a development server

Attach a database

Ship to production

Work from another machine

Every command

Hand this page to your agent

Your part

Your agent’s part

Report back

Next steps