Quickstart: deploy a GitHub repo to a VPS in 5 steps

Sign in with GitHub, run the Add server command on a fresh Ubuntu LTS server, pick your repository, check the plan ox detected, and press Deploy. ox builds the app on your server and starts it as a systemd service behind Caddy. Traffic moves to it once its health check passes. A simple repo needs no config file.

To try ox before you deploy your own app, fork one of the example projects.

Before you start

You need these. ox installs everything else.

• A GitHub account and a repository with an app in it.
• A fresh Ubuntu LTS server with at least 1 GB of memory, 10 GB of free disk, ports 80 and 443 free, and IPv4 internet access.
• Root login to that server over SSH, with your own key or the root password. ox turns password login off, so if the server has no key of yours, Add a server can put your GitHub SSH keys on it.

1. Sign in with GitHub

Open the sign-in page and press Continue with GitHub. ox asks GitHub only for what it needs to read your repositories and get push events.

2. Add a server

In the dashboard, press Add a server. Three short steps follow: what the server needs, how you will log in once ox turns password login off (your SSH keys from GitHub, or the key the server already has), and Get my command, one command with a fresh token in it. Run it on the server as root. The page shows when the server connects.

curl -fsSL https://deploywithox.com/install/<token> | sudo bash

The script installs the ox agent and Caddy. When it finishes, the server shows up in the dashboard. The token in the command works once and expires, so copy a new command from the dashboard for each server.

3. Add the repository as a project

Press New project, pick the server, pick the repository, and press Continue.

You can also do this from a terminal. Install the ox CLI and sign in once. The steps below show the command for each button.

curl -fsSL https://deploywithox.com/install.sh | sh
ox login
ox new <owner/repo> --server <server>

4. Review the plan

The What ox will run card shows the start command, build steps, services and variables ox detected from the repo. Fill in what it still needs, such as a SECRET_KEY. Variables explains how to set a secret.

If detection got something wrong, add an ox.toml to the repo for just that part. The framework guides show a complete one for Django, Next.js, FastAPI, Node, Laravel, Rails and static sites.

ox check                     # offline: validate ox.toml, show the plan and missing variables
ox review <project>          # what the first deploy still needs

5. Deploy and follow the log

Press Deploy, or run the command below. The log streams while ox builds, migrates and starts the new release. Traffic switches once the health check passes.

ox deploy <project> --wait   # stream the run, exit with its result
ox logs <project> --follow   # the app's logs

If the run fails, the log names the failed step and the fix, and nothing changes for your visitors. Troubleshooting covers the common failures.

Next steps after your first deploy

• Add a custom domain with HTTPS: create one A record and Caddy gets the certificate.
• Read your app's logs live, or search them.
• Roll back a deploy that went wrong, without a rebuild.
• See your daily backups and add an S3 bucket.
• Use the CLI for everything the dashboard does.
• See what ox locked down on your server, and check it yourself.

The Operate section covers the rest of running your app.