# ox

> ox deploys a GitHub repository onto the user's own Ubuntu LTS server (a VPS) with systemd and Caddy, no Docker. The user signs in to ox Cloud, the hosted control plane; their server runs only a small agent and Caddy.

Happy path for a new app:

1. Sign in with GitHub at https://deploywithox.com/login.
2. Add a server: run the Add server command the console shows on a fresh Ubuntu LTS server.
3. Add the repository as a project on that server.
4. Review the plan ox detected (start command, services, variables) and answer what it still needs.
5. Deploy, and follow the run's log.

Config: `ox.toml` at the repo root is optional. Every key is optional, and ox detects what is left out from the repo's own files. The full authoring contract (keys, detection, services, variables, examples, common mistakes) is the ox.toml skill linked below; the config reference says the same for people.

CLI (macOS or Linux):

```
curl -fsSL https://deploywithox.com/install.sh | sh
ox login                     # approve a code in the browser
ox check                     # offline: validate ox.toml, show the resolved plan and missing variables
ox deploy <project> --wait   # deploy, stream the run's log, exit with its result
ox logs <project> --follow   # the app's logs
ox vars <project>            # the project's variables
ox help                      # every command
```

Every client command takes `--json` and exits non-zero on failure.

Rules for agents:

- Run `ox check` in the repo before deploying, and fix what it reports.
- Never put secrets in `ox.toml`. They live in the dashboard or in `ox vars set <project> KEY`, which asks for the value.
- Do not invent keys. Use only keys from the skill or the config reference; unknown keys are errors.
- Prefer `--json` when parsing output.
- Ask the user before deploying, deleting, or rolling back.

## Docs

The docs pages, as Markdown:

- [ox docs: deploy a GitHub repo to your own Ubuntu VPS](https://deploywithox.com/docs.md): Deploy a GitHub repo to your own Ubuntu server with ox, on systemd and Caddy, no Docker. Start with the quickstart, a framework guide or the ox.toml keys.
- [ox.toml reference: every key, default and example](https://deploywithox.com/docs/config.md): The ox.toml reference: every key with its default, what ox detects from your repo, services, variables, and working examples for Next.js, Python, Go, SPAs.

More:

- [ox.toml skill for AI agents](https://deploywithox.com/ox-skill.md): the same contract as one Markdown file to load as context.
- [Features](https://deploywithox.com/features): what ox does for an app, in short.

## Optional

- [Story](https://deploywithox.com/story): why ox was built, by the person who builds it.
- [Privacy](https://deploywithox.com/privacy): what ox stores, and how to reach the team with questions.
- [Terms](https://deploywithox.com/terms): the terms of service.