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

To deploy a GitHub repo to your own VPS with ox, sign in with GitHub, run the Add server command on a fresh Ubuntu LTS server, pick the repository, check the plan ox detected, and press Deploy. ox builds the app on the server, starts it as a systemd service behind Caddy, and moves traffic once the health check passes. Most repos need no config file.

Before you start

You need a GitHub account, a repository with an app in it, and a fresh Ubuntu LTS server you can reach as root over SSH, with at least 1 GB of memory, 10 GB of free disk, and ports 80 and 443 free. ox installs everything else.

1. Sign in with GitHub

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

2. Add a server

In the console press Add a server. It shows one command with a fresh token in it. Run it on the server as root.

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

The token works once and expires, so copy the command from the console each time. The script installs the ox agent and Caddy, then the server shows up in the console.

3. Add the repository as a project

Press New project, pick the server, pick the repository, and press Continue. From a terminal, ox new <owner/repo> --server <server> does the same.

4. Review the plan

The What ox will run card shows the start command, build steps, services and variables ox detected from the repo. Answer what it still needs, such as a SECRET_KEY, and add an ox.toml only for what detection got wrong. The framework guides show a complete one for Django, Next.js, FastAPI, Node, Laravel and static sites, and Variables explains how to set a secret.

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 run's log streams as it builds, migrates, starts the new release and switches traffic once the health check passes.

curl -fsSL https://deploywithox.com/install.sh | sh
ox login
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 step and the fix. Troubleshooting covers the common ones.

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.

The Operate section covers the rest of running your app day to day.