Metadata-Version: 2.4
Name: hoist-cli
Version: 0.1.0
Summary: Put a local app on a public HTTPS URL, with one command.
Author: nikhilcherry
License: MIT
Project-URL: Homepage, https://github.com/nikhilcherry/hoist
Project-URL: Issues, https://github.com/nikhilcherry/hoist/issues
Keywords: cloudflare,tunnel,systemd,hackathon,deploy,qr
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

<img src="docs/hero.svg" alt="hoist — put a local app on a public HTTPS URL, with one command" width="100%">

<p align="center">
  <img src="https://img.shields.io/github/actions/workflow/status/nikhilcherry/hoist/ci.yml?branch=main&amp;label=ci&amp;style=flat-square" alt="CI status">
  <img src="https://img.shields.io/badge/python-3.9%2B-blue?style=flat-square" alt="Python 3.9+">
  <img src="https://img.shields.io/badge/dependencies-none-3fb950?style=flat-square" alt="No dependencies">
  <img src="https://img.shields.io/badge/license-MIT-lightgrey?style=flat-square" alt="MIT license">
</p>

<p align="center">
  <img src="docs/demo-up.svg" width="584" alt="hoist up publishing a directory: it picks a free port, writes a systemd unit, adds an ingress rule, routes DNS, reloads cloudflared, verifies the public URL, then prints it with a scannable QR code">
</p>

<p align="center">
  <img src="docs/demo-dashboard.gif" width="820" alt="Push to deploy and rollback: the running app shows v3, the Deployments page lists three deploys, one click on Roll back confirms and returns to v2 in 0.4 seconds, and the app now shows v2">
</p>

That's it. Your app is running as a managed service, it survives crashes and
reboots, it has a real certificate, and the QR code on screen puts it on a
judge's phone in about two seconds.

hoist started as that one command and has grown into a small self-hosting
platform for one machine or a team: push-to-deploy from git, a web dashboard,
databases and 46 one-click apps, backups, branch previews, per-person
permissions, and zero-downtime deploys. It is still **one standard-library
Python package with no dependencies**, and it was measured against Dokploy on
the same laptop (see [Measured](#measured)).

> Every screenshot here is a real run, rendered from the terminal output by
> [`scripts/make_docs_images.sh`](scripts/make_docs_images.sh). The QR codes in
> them scan.

## Why

Getting a local project onto a shareable URL is five fiddly steps that are
easy to get wrong under time pressure:

1. pick a port nothing else is using
2. write a systemd unit so it keeps running
3. add an ingress rule to your Cloudflare Tunnel config
4. create the DNS record
5. restart the tunnel, then find the URL again to share it

`hoist up` is those five steps. `hoist down` is their exact inverse.

## Install

```bash
pipx install hoist-cli        # or: pip install --user hoist-cli
# latest from git:  pipx install git+https://github.com/nikhilcherry/hoist
```

Or straight from source, no packaging step:

```bash
git clone https://github.com/nikhilcherry/hoist
cd hoist && pip install -e .
```

**Zero runtime dependencies** — standard library only, including the QR
encoder. It works on a conference laptop with no internet.

Check your setup any time:

```bash
hoist doctor
```

<img src="docs/demo-doctor.svg" width="100%" alt="hoist doctor checking systemd, lingering, cloudflared, the tunnel config and id, ingress hostnames, the default domain, and tracked apps">

`doctor` never changes anything. When something is off it prints the exact
command that fixes it.

## One-time setup: no password prompts

cloudflared does not watch its config file, so new ingress rules only take
effect on restart -- which is the only reason root is involved. If your
config is root-owned, sudo will prompt, and `hoist up` then has to run in a
real terminal rather than any wrapper that lacks a TTY.

To remove the prompt for good, run these once (`hoist doctor` prints them
with your paths filled in):

```bash
sudo chown $USER /etc/cloudflared/config.yml
echo "$USER ALL=(root) NOPASSWD: /usr/bin/systemctl restart cloudflared" | sudo tee /etc/sudoers.d/hoist
sudo chmod 440 /etc/sudoers.d/hoist
```

The sudoers rule is scoped to exactly one command -- restarting cloudflared --
not blanket root.

## A note on wildcard DNS

If your zone has a wildcard record (`*.example.com`), every hostname resolves
and returns *something*, so a half-finished publish looks like it worked --
you get someone else's 404 instead of an error. After reloading the tunnel,
hoist fetches the public URL and compares it against what your app serves
locally, and tells you when a different server answered.

## Requirements

- Linux with `systemd --user`
- [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)
  with a tunnel already created, and a domain on Cloudflare
- Python 3.9+
- Docker, *only* for the Docker features: Dockerfile and Compose repos,
  `hoist db`, `hoist template` and buildpacks (optional). Plain apps don't need it.

Only want a LAN URL? Skip cloudflared entirely and use `--local`.

## Commands

| Command | What it does |
| --- | --- |
| `hoist up [dir]` | Run a project and publish it. Detects the start command. |
| `hoist up <git-url>` | Clone, build and publish a repo, then redeploy on every push. |
| `hoist sync <name>` | Redeploy a repo app now if its branch moved (the timer runs this). |
| `hoist share [dir]` | Serve a folder of files publicly. No project needed. |
| `hoist ls` | Every hoisted app, its port, health and URL. |
| `hoist down <name>` | Stop it and remove its ingress rule. |
| `hoist logs <name> [-f]` | Tail the app's journald logs. `--deploys` shows the push-to-deploy log. |
| `hoist restart <name>` | Restart the service. |
| `hoist url <name>` | Print the URL (pipe it into `xdg-open`, Slack, etc). |
| `hoist qr <name>` | Reprint the QR code. |
| `hoist adopt <name> --port N` | Publish something already running (Docker, `npm run dev`). |
| `hoist dash` | Open the web dashboard (below). `--service` keeps it running. |
| `hoist pause / resume <name>` | Stop or restart redeploying a repo app on push. |
| `hoist stop / start <name>` | Stop an app's process, keeping its URL and config. |
| `hoist sync <name> --to <sha>` | Roll back to an earlier commit (pauses auto-deploy). |
| `hoist limit <name> --memory 512M --cpu 50%` | Cap an app's resources. |
| `hoist db postgres --name votes` | A database in Docker: PostgreSQL, MySQL, MariaDB, Redis or MongoDB. |
| `hoist link <db> <app>` | Put the database's URL in the app's environment and restart it. |
| `hoist backup <db> [--daily] [--restore F] [--offsite gdrive:hoist]` | Back up, schedule, restore, copy off-site. |
| `hoist template <id>` | 46 one-click apps; `hoist template add <Compose file or URL> --name x` adds your own. |
| `hoist stage <name> staging` | Label an app production, staging, development or preview; permissions can follow the label. |
| `hoist previews <name> on` | Every branch gets its own preview app, removed when the branch is deleted. |
| `hoist exec <name> -- <command>` | Run one command in the app's folder, container or stack. |
| `hoist webhook <name>` | Deploy within a second of a push (GitHub or GitLab webhook). |
| `hoist backup <stack>` | Back up a Docker stack's volumes too, not just databases. |
| `hoist notify <webhook>` | Deploy, failed-build and downtime alerts to Discord, Slack, ntfy, Telegram or email (`smtps://…`). |
| `hoist doctor` | Check systemd, cloudflared, tunnel, domain, permissions. |

<img src="docs/demo-ls.svg" width="557" alt="hoist ls listing two apps with their port, state and URL — one published through the tunnel, one on the LAN">

### Useful flags

```bash
hoist up ./api --name api --port 8000        # pin the name and port
hoist up ./api --cmd 'uvicorn main:app --port $PORT'
hoist up ./api --env DATABASE_URL=postgres://localhost/dev
hoist up ./site --local                      # LAN URL + QR, no tunnel, no internet
hoist up ./site --domain example.com         # remembered for next time
```

## Push to deploy

Point `hoist up` at a repo instead of a folder and your teammates deploy by
pushing. They need no access to your machine, no account and no CLI:

```bash
hoist up github.com/team/project --name team
# ✓ cloned main @ a9f8649 mate: first page
# ✓ built
# ✓ watching main — every push redeploys (checks every 20s)
#   https://team.example.com
```

hoist clones into its own checkout, runs the install/build the project needs
(`npm ci` + `npm run build`, a `.venv` from `requirements.txt`, …), starts
it, and installs a systemd timer that fetches the branch every 20 seconds.
A new commit is checked out, built, and the service restarted.

- **A broken push never takes the demo down.** If the build fails, the app
  keeps serving the last good commit, `hoist ls` shows the failure, and that
  commit is not retried until someone pushes again.
- **Offline is fine.** A failed fetch is skipped; the next tick tries again.
- **Polling, not webhooks**, so nothing has to accept inbound connections and
  it works on venue Wi-Fi that blocks them.
- Private repos use whatever git credentials this machine already has
  (`gh auth login`, an SSH key).

```bash
hoist up git@github.com:team/api.git --branch demo   # track another branch
hoist up github.com/team/web --build 'npm ci && npm run build:prod'
hoist up github.com/team/web --no-sync               # deploy once, don't watch
hoist logs team --deploys -f                         # watch deploys happen
hoist sync team --force                              # rebuild right now
```

`hoist down team` stops the watcher and deletes the checkout as well.

## The dashboard

```bash
hoist dash --service      # runs on 127.0.0.1:7457, survives reboots; prints a sign-in link once
hoist dash --public dash  # optional: also at https://dash.<your-domain>, behind the same token
```

<img src="docs/dashboard.png" width="100%" alt="The hoist dashboard overview: three live apps, public-check column, and CPU, memory and disk for the machine">

<table>
  <tr>
    <td width="50%"><img src="docs/dashboard-app.png" alt="An app page: the route strip from source to build to process to port to network, uptime and response cards, resources, and a QR code to open it on a phone"><br><sub><b>An app</b> — the route strip shows which hop is broken, plus a QR code for the phone.</sub></td>
    <td width="50%"><img src="docs/dashboard-machine.png" alt="The Machine page: CPU, memory, swap, disk and tunnel status with live charts for CPU, memory and network"><br><sub><b>The machine</b> — CPU, memory, disk and tunnel health, with the <code>hoist doctor</code> checks below.</sub></td>
  </tr>
</table>

Everything the CLI does, in one place, for the whole team:

- **Overview** that answers "can a judge open every app right now?" — each app's
  public URL is checked every 30 s, and anything not answering says why
  (*nothing is listening on port 8420*, *its public URL answers 502*).
- **The route strip** on every app: source → build → process → port → public URL,
  each hop live, so you see which one broke.
- **Deployments** with the commit, author, trigger and build log of every push;
  one-click **rollback** (instant when the release is still on disk) and redeploy;
  with a webhook a push is live in about 0.3 s for a plain app and about 2 s for a
  Dockerfile app (measured, with Dokploy on the same laptop, in [docs/benchmark.md](docs/benchmark.md)).
- **Live logs** streamed from the journal, with search, follow and download —
  the app's output or the deploy log.
- **Environment variables** editor (paste a `.env`), **resource limits**, stop/start,
  pause auto-deploy, take down.
- **New app** from a git URL or a folder, with the build streaming as it runs.
- **Routes** (every hostname on the tunnel, hand-written ones too, with a one-hour
  uptime strip), **Machine** (CPU, memory, disk, the `hoist doctor` checks with
  copyable fixes), **notifications** and a QR code for every app.
- **Databases** with a connection card, one-click linking, daily backups,
  restore and download; **ready-made apps** from the new-app drawer;
  **branch previews**; a **console** that runs one command in the app.
- **Team**: everyone gets their own sign-in link (`hoist dash --add-user shreyas`; `--role viewer` for read-only, or
  `--role custom --can operate,backups --apps api --stages staging` to pick exactly what they can do and where), and an audit log records
  who deployed, rolled back or changed what.
- **Terminal**: an interactive shell in the app, its database or its stack.
- **Machines**: link other machines running hoist and manage them all from one dashboard.
- Command palette on <kbd>Ctrl</kbd> <kbd>K</kbd>, <kbd>N</kbd> for a new app, light and dark.

How it stacks up against Dokploy, feature by feature and measured on the same
laptop: [docs/vs-dokploy.md](docs/vs-dokploy.md); the measured side-by-side is
[docs/benchmark.md](docs/benchmark.md).

Zero dependencies like the rest of hoist: a standard-library server and one page
of plain JavaScript, fonts bundled so it works with no internet. A token guards
it (HttpOnly cookie plus a header every write must carry), because behind a
tunnel every request arrives from 127.0.0.1.

### How a deploy can never take the demo down

Dockerfile and buildpack apps also redeploy with **no downtime at all**: the new
container starts beside the old one behind a small supervisor, traffic moves when
it answers, and a version that never answers is discarded.

Every deploy is exported from git into its own release directory, built there,
and only then made live by swapping a `current` symlink and restarting. The
running process keeps serving its own release the whole time, so a push that
fails to build — or deletes files halfway — never touches it. The last four
releases are kept, which is why rolling back to one of them needs no rebuild.

### Docker apps

A repo with a `compose.yml` runs as a Compose stack and one with only a
`Dockerfile` is wrapped in one; both are built before they go live, like
everything else. Their CPU and memory are read from the containers' own
cgroups, and their limits go to Docker. Databases (`hoist db`) and templates
(`hoist template`) are Docker apps too, so they get logs, restart, limits and
the dashboard for free.

## Measured

Same laptop, same Dockerfile app, same push webhook, a 50 ms poller watching the
public URL; full method and raw logs in [docs/benchmark.md](docs/benchmark.md),
feature comparison in [docs/vs-dokploy.md](docs/vs-dokploy.md).

| | hoist | Dokploy v0.31.0 |
| --- | --: | --: |
| Push → live, median of 6 deploys | **1.54 s** | 2.53 s |
| Downtime during the swap | **0.00 s** | ≈ 0.10 s |
| Broken build | old version keeps serving | old version keeps serving |
| Dashboard API latency | 3.5 ms median | 24 ms |

Benchmarking found real bugs (a Nagle/delayed-ACK stall that made the dashboard's
API take 45 ms, a stale-container swap race, a supervisor that polled Docker too
often), each now pinned by a test. Re-run it with `scripts/bench_deploy.sh`.

## What it detects

| Found in the directory | Start command |
| --- | --- |
| `Procfile` with a `web:` line | that line |
| `package.json` | `npm start`, else `npm run dev` / `serve` / `preview` |
| `manage.py` | `python3 manage.py runserver 127.0.0.1:$PORT` |
| `app.py` / `main.py` / `server.py` / `wsgi.py` | `python3 <file>` |
| `Cargo.toml` | `cargo run --release` |
| `go.mod` | `go run .` |
| `index.html` or any `*.html` | `python3 -m http.server $PORT` |

Anything else: tell hoist how to start it with `--cmd`.

## Telling hoist how to start your app

`--cmd` is for when the table above has no row for your project, or the guess
it makes is wrong:

```bash
hoist up ./api --cmd 'uvicorn main:app --port $PORT'
```

### Rule 1: listen on the port hoist gives you

hoist picks a free port, then publishes *that* port. If your app ignores it
and listens on its own hardcoded port instead, hoist waits, then tells you
`nothing listening on port 43581` — your app is running perfectly well, just
somewhere nobody is looking. This is the one thing that has to be right.

There are two ways to get the number, and they are equivalent — use whichever
suits your app:

- **Write `$PORT` in the command.** hoist substitutes the real number before
  the app ever starts, so `--port $PORT` becomes `--port 43581`.
- **Read `PORT` from the environment.** hoist always sets it, so
  `process.env.PORT` in Node or `os.environ["PORT"]` in Python just works,
  and you can leave `$PORT` out of the command entirely.

### Rule 2: wrap it in single quotes

```bash
hoist up ./api --cmd 'uvicorn main:app --port $PORT'    # right
hoist up ./api --cmd "uvicorn main:app --port $PORT"    # wrong
```

With double quotes **your shell** expands `$PORT` before hoist ever sees it.
It is almost never set in your shell, so hoist receives `--port` followed by
nothing and the app dies with a confusing error. Single quotes pass the text
through untouched, which is what you want.

### Rule 3: don't background it

The command must run in the foreground and stay there — that is how systemd
knows your app is alive. Anything that forks and returns immediately makes
systemd think it exited:

```bash
--cmd 'npm start &'                  # no: the & backgrounds it
--cmd 'gunicorn app:app --daemon'    # no: --daemon forks
--cmd 'pm2 start server.js'          # no: pm2 is its own supervisor
```

Drop the `&`, the `--daemon`, the `pm2`. hoist is the supervisor.

### Recipes

| Stack | `--cmd` |
| --- | --- |
| Node / Express | `'node server.js'` — read `process.env.PORT` |
| Next.js | `'npx next dev -p $PORT'` |
| Vite | `'npm run dev -- --port $PORT'` |
| FastAPI | `'uvicorn main:app --port $PORT'` |
| Flask | `'flask run --port $PORT'` |
| Django | `'python3 manage.py runserver 127.0.0.1:$PORT'` |
| Gunicorn | `'gunicorn app:app --bind 127.0.0.1:$PORT'` |
| Streamlit | `'streamlit run app.py --server.port $PORT'` |
| Go | `'go run . --port $PORT'` |
| Rust | `'cargo run --release -- --port $PORT'` |
| A folder of files | `'python3 -m http.server $PORT'` |

### What else you get

- **It runs in the directory you hoisted**, so relative paths in the command
  and in your code behave as they do when you run it by hand.
- **Shell syntax works.** If the command contains `&&`, a pipe, a redirect or
  a glob, hoist runs it through `sh -lc` instead of executing it directly, so
  `--cmd 'npm run build && npm start'` is fine.
- **Version managers work.** If the binary isn't on your `PATH` when you run
  `hoist up`, the command is resolved by a login shell at start time instead,
  so things installed through nvm, pyenv or rustup are still found.
- **Extra environment variables** go in with `--env`, repeated as needed:
  `--env DATABASE_URL=postgres://localhost/dev --env DEBUG=1`.

### When it doesn't come up

You don't have to go looking. `hoist up` waits for the port to open, and if it
doesn't, it says which of the three ways it went wrong and prints the last few
lines the app logged before dying:

| What you see | What it usually means |
| --- | --- |
| `keeps crashing on startup` | the app exits as fast as it starts — a mistyped binary, a missing dependency, an import error. The tail says which. |
| `failed to start` | systemd couldn't run the command at all |
| `nothing listening on port N` | the app is running, on a *different* port. Rule 1. |

For more than the tail, `hoist logs <name> -f` follows the app's journald
output live. Nine times out of ten it is one of the three rules above: wrong
port, double quotes, or a command that backgrounded itself.

Already have the app running and only want it public? Skip `--cmd` entirely
and adopt the port it is already on:

```bash
hoist adopt api --port 8000
```

## Limitations

Honest list, so you can decide quickly:

- **Linux with `systemd --user` only.** No macOS or Windows host support.
- **Cloudflare Tunnel is the only public-URL backend** (plus `--local` for a LAN
  URL). No Caddy, Traefik or ngrok mode yet.
- **One machine.** `Machines` in the dashboard links other hoist hosts, but there
  is no scheduler, clustering or failover.
- **Zero-downtime rollover is for Dockerfile and buildpack apps only.** Plain
  apps restart in well under a second; Compose stacks, templates and databases
  stop and start on purpose, since two copies of a database could corrupt it.
- Benchmarked on one laptop against one competitor ([details](docs/benchmark.md));
  treat the numbers as a method, not a universal claim.
- Docker features are tested on Docker Engine only (not Podman).

## Safety around your tunnel config

The cloudflared config is usually a live file with hand-written rules in it,
so hoist is deliberately careful:

- Every rule it adds is tagged with a `# hoist:<name>` marker, and it will
  only ever remove rules carrying its own marker.
- It **refuses** to touch a hostname you configured by hand.
- The config is edited as text, so your comments, ordering and indentation
  survive. `hoist down` restores the file byte-for-byte.
- Every write makes a timestamped backup first.
- After writing it runs `cloudflared tunnel ingress validate`, and rolls back
  to the backup if the config is rejected.
- The catch-all rule is always kept last, where cloudflared requires it.

`hoist down` intentionally leaves the DNS record in place: deleting DNS is
slow to undo, and reusing the same name later just works.

## Hackathon notes

- **Offline?** `--local` gives you a LAN URL and a QR code with no internet
  and no cloudflared. Everyone on the venue wifi can reach your demo.

  <img src="docs/demo-local.svg" width="566" alt="hoist up --local serving a directory on the LAN IP with a QR code, no tunnel and no internet involved">

- **Demo day.** `hoist qr <name>` fills the terminal with a code judges can
  scan while you talk. No "let me just find the link".
- **Webhooks.** Stripe, Twilio, GitHub and friends need a real HTTPS URL. A
  hoisted app gives you a stable one that survives laptop sleep.
- **Your laptop lid.** Services are `Restart=on-failure` and enabled, so they
  come back after a reboot. Run `sudo loginctl enable-linger $USER` once so
  they also survive logout — `hoist doctor` reminds you.

## How it works

<img src="docs/architecture.svg" width="100%" alt="Four stages: detect.py picks a free port and start command, service.py writes and starts a user systemd unit, tunnel.py adds an ingress rule and routes DNS, qr.py renders the URL as a scannable code">

State lives in `~/.config/hoist/apps.json`, written atomically and under a lock
so concurrent deploys can't corrupt it. Nothing is hidden anywhere else: hoist
only ever touches that file, its own systemd units and timers, its release and
checkout directories, and the ingress rules it marked.

Beyond the four stages above: `source.py` clones, builds and releases repos,
`containers.py` runs Docker apps, databases and templates, `front.py` is the
small supervisor that gives Docker apps their zero-downtime rollover, `notify.py`
sends alerts, and `dash/` is the dashboard (standard-library server plus one
page of plain JavaScript).

## Development

```bash
pip install -e ".[dev]"
pytest -q
```

Deploy performance is checked by `scripts/bench_deploy.sh` (needs Docker);
results are committed under `docs/bench-results/`.

The QR encoder is written from scratch against the spec so the tool has no
dependencies. It is tested two ways: a golden matrix in the unit tests, and
`scripts/qr_conformance.py`, which renders codes to PNG and decodes them with
`zbarimg` in CI.

The screenshots in `docs/` are captured from real runs rather than drawn by
hand, so they cannot drift from what the tool actually prints:

```bash
scripts/make_docs_images.sh                  # the --local screenshots
scripts/make_docs_images.sh --public NAME    # also re-shoot the publish flow
```

`--public` performs a real publish, so pass a hostname you already use for
testing — it rewrites your cloudflared config and restarts the tunnel. The
script re-decodes every QR it renders with `zbarimg` at the end, and redacts
the tunnel id out of the `doctor` shot.

## Contributing and security

See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md) and the [CHANGELOG](CHANGELOG.md).

## License

MIT
