From cbb7346fd6539b7f2a7d0984d6efbab5b393311a Mon Sep 17 00:00:00 2001
From: Shihaam Abdul Rahman <shihaam@shihaam.me>
Date: Sat, 22 Aug 2026 22:49:51 +0500
Subject: [PATCH] install instructions

---
 README.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0a27c39
--- /dev/null
+++ b/README.md
@@ -0,0 +1,105 @@
+# HTTP Toolkit (self-hosted)
+
+A self-hosted, single-file build of [HTTP Toolkit](https://httptoolkit.com): the
+server and the web UI compiled into one binary called `httptoolkit`.
+
+## Install
+
+Download the latest release into `~/.local/bin`:
+
+```bash
+mkdir -p ~/.local/bin
+wget -O ~/.local/bin/httptoolkit \
+  "https://git.shihaam.dev/shihaam/httptoolkit/releases/download/$(curl -sD - -o /dev/null "https://git.shihaam.dev/shihaam/httptoolkit/releases/latest" | grep -oP '(?<=tag/)[^"\r\n]+')/httptoolkit"
+chmod +x ~/.local/bin/httptoolkit
+```
+
+Make sure `~/.local/bin` is on your `PATH` (most distros do this already):
+
+```bash
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+```
+
+## Run as a systemd user service
+
+Create the unit:
+
+```bash
+mkdir -p ~/.config/systemd/user
+cat > ~/.config/systemd/user/httptoolkit.service <<'EOF'
+[Unit]
+Description=HTTP Toolkit (self-hosted)
+After=network.target
+
+[Service]
+ExecStart=%h/.local/bin/httptoolkit --port 8080 --no-open
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+EOF
+```
+
+Start it:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user start httptoolkit
+```
+
+Then open <http://localhost:8080>.
+
+### Managing the service
+
+```bash
+systemctl --user status httptoolkit     # check it's running
+systemctl --user restart httptoolkit
+systemctl --user stop httptoolkit
+journalctl --user -u httptoolkit -f     # follow logs
+```
+
+Start it automatically at login:
+
+```bash
+systemctl --user enable httptoolkit
+```
+
+To keep it running when you're not logged in (e.g. on a headless box), enable
+lingering for your user:
+
+```bash
+loginctl enable-linger "$USER"
+```
+
+## Updating
+
+Re-run the download command above, then restart the service:
+
+```bash
+systemctl --user restart httptoolkit
+```
+
+## Options
+
+```
+  -p, --port <port>          Port to serve the web UI on (default: 8080)
+      --server-port <port>   HTK management API port (default: 45457)
+      --mockttp-port <port>  Mockttp admin port (default: 45456)
+      --no-open              Don't open a browser automatically
+  -h, --help                 Show this help
+```
+
+`--no-open` matters for the service: without it the binary tries to launch a
+browser on start.
+
+## Building from source
+
+Requires Docker. The build runs in a container that clones upstream, applies the
+patches in `patches/` and the overlay in `overlay/`, then compiles the binary:
+
+```bash
+docker compose run --build --rm release-httptoolkit
+```
+
+The result lands in `builds/httptoolkit`.