From 94e50e19f3d21ef4f241511f4ff16dbc0c09a9eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?T=C3=A9o=20Goulois?= Date: Mon, 9 Nov 2026 18:49:10 +0100 Subject: [PATCH 1/2] docs: rewrite the README as the front door, and fit the GitHub templates to an open-source project The README now says what Localify is, shows localify dev, and covers install, the commands people use, coding agents, Localify Cloud, privacy, contributing and the license. Build instructions and the repository layout move to CONTRIBUTING.md. Removes assets/logo-icon-2-white.svg, which nothing references. --- .github/ISSUE_TEMPLATE/bug_report.md | 26 ++- .github/ISSUE_TEMPLATE/config.yml | 5 +- .github/ISSUE_TEMPLATE/feature_request.md | 8 +- .github/pull_request_template.md | 14 +- README.md | 247 ++++++++-------------- assets/logo-icon-2-white.svg | 4 - 6 files changed, 127 insertions(+), 177 deletions(-) delete mode 100644 assets/logo-icon-2-white.svg diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index c1df4149..f29819f8 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,9 +1,17 @@ --- name: Bug report -about: Something is not working as expected +about: Something in Localify doesn't work as it should labels: bug --- + + **What happened** **What you expected** @@ -15,10 +23,16 @@ labels: bug **Environment** -- OS and version: -- Localify version (`localify --version` or desktop app version): -- Install method (desktop app / CLI build): +- OS and version (and Linux distribution): +- Localify version (`localify --version`, or Localify → About Localify in the app): +- Installed with: desktop app / `install.sh` / built from source +- Framework of the app you run through Localify, if it matters (Next.js, Vite…): -**Logs** +**Output** - + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 0deddeb2..723ba679 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,5 +1,8 @@ blank_issues_enabled: true contact_links: + - name: User guide + url: https://github.com/Synapsr/Localify/blob/main/docs/README.md + about: How to install Localify, run your apps through it, and fix common problems. - name: Security vulnerability url: https://github.com/Synapsr/Localify/security/advisories/new - about: Please report security issues privately, not in public issues. + about: Report security issues privately, not in public issues. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index b9286d8d..6e6c5f37 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -4,10 +4,10 @@ about: Suggest an improvement or a new capability labels: enhancement --- -**Problem** +**What you're trying to do** - + -**Proposed solution** +**What you'd like Localify to do** -**Alternatives considered** +**What you do today instead** diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 7d23bf7b..9aeb9530 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,13 +1,17 @@ ## Summary - + ## Checks -- [ ] `cargo fmt`, `cargo clippy -- -D warnings`, and `cargo test` pass (Rust changes) -- [ ] `pnpm run typecheck` passes (`desktop-ui/` changes) -- [ ] `pnpm web:typecheck` and `pnpm web:build` pass (`apps/web/` changes) -- [ ] Docs updated if behaviour changed + + +- [ ] Rust: `cargo fmt`, `cargo clippy -- -D warnings` and `cargo test` pass +- [ ] `desktop-ui/`: `pnpm run typecheck` and `pnpm desktop:test` pass +- [ ] `apps/web/`: `pnpm web:typecheck` and `pnpm web:build` pass, with the same keys in every locale +- [ ] `apps/cloud/`: `pnpm cloud:typecheck` and `pnpm cloud:test` pass +- [ ] Users will notice this change, and I added a note in `changes/` +- [ ] Docs are updated where behaviour changed ## Contributor license agreement diff --git a/README.md b/README.md index 3d8fdc66..5ed18315 100644 --- a/README.md +++ b/README.md @@ -1,193 +1,126 @@ -# Localify - -Localify gives each local project a stable `.localify` domain with trusted -HTTPS, so you open `https://my-app.localify` instead of remembering which -`localhost` port a service landed on. OAuth callbacks, cookies, and CORS origins -get a fixed HTTPS address, and coding agents reach your app at a URL that stays -the same between runs. - -It ships as a Rust CLI and daemon plus a Tauri desktop app. Everything that runs -on your machine is free, with no limit on projects or domains. - -## What it does - -- Routes memorable `.localify` domains to local services. -- Generates and trusts local TLS certificates. -- Supports HTTP, HTTPS, WebSockets, static directories, and wildcard domains. -- Groups domains and services into projects with worktree-aware development - commands. -- Shows request logs, project controls, and diagnostics in the desktop app. -- Starts services in the desktop app's terminal from the CLI (`localify dev --in-app`), - and reads their output, status, and stops them from anywhere (`localify logs`, - `services status`, `stop`). -- Gives coding agents every action through an MCP server (`localify mcp`), including - starting services in the app and removing the worktrees they are done with. See - [Coding agents](docs/README.md#coding-agents). +

+ Localify +

-## Install +

Localify

-### Desktop app +

+ Stable https://<name>.localify URLs for the apps you run on your machine. +

-Download the app from [localify.dev](https://localify.dev). On first launch it -asks for your administrator password once, then sets up HTTPS, DNS, and the -daemon. The first time you need HTTPS in a browser, macOS asks you to confirm the -certificate once. +

+ Website · + User guide · + Changelog · + Contributing +

-### CLI from source +Localify is a local development proxy. A Rust daemon runs its own DNS server, issues +trusted certificates, and routes `https://journal.localify` to the port your dev server +listens on. You stop remembering ports, and OAuth callbacks, cookies, CORS origins and +webhooks get a fixed HTTPS address. Coding agents use the same URLs through Localify's +MCP server. -You need Rust stable, on macOS or Linux. On Linux, read -[docs/linux.md](docs/linux.md) first. +It ships as a command line tool for macOS and Linux and a desktop app for macOS. +Everything that runs on your machine is free, with no limit on projects or domains. -```bash -git clone https://github.com/Synapsr/Localify.git -cd Localify -cargo build --release --bin localify -sudo install -m 755 target/release/localify /usr/local/bin/localify -``` - -Set up the local certificate authority, DNS and the background service: +## A quick look ```bash -localify install +cd ~/code/journal +localify dev ``` -On macOS this asks for an administrator's approval once. After that nothing of -Localify's runs as root: the daemon runs as you, starts at boot, and only this Mac -can reach it unless you run `localify lan enable`. `localify uninstall --force` -removes all of it, with one more approval. - -HTTP and Node.js work right away. For HTTPS in browsers, run `localify trust` once -and confirm in the macOS window. - -On Linux with systemd it works the same way: one `sudo` password at install, then nothing -of Localify's runs as root. The install also trusts the certificate, so HTTPS works in -tools that use the system store. See [Localify on Linux](docs/linux.md). - -## Local CLI example - -With the setup above done, point a domain at a service on port 3000: - -```bash -localify register my-app.localify --route "/=3000" -localify status -localify logs -f -``` - -The app is now at `https://my-app.localify`. The -[CLI reference](docs/README.md) covers routes, wildcards, and static directories. - -On macOS, `localify init-project my-app --yes` creates a project from the current -folder instead, with `my-app.localify` as its default domain. Localify picks a -free target port unless you provide one. - -## Telemetry - -Official desktop builds send product analytics and error reports to PostHog. -They send explicit events only, with no autocapture, and analytics events never -include project names, domains, request logs, or local paths. Before an error -report is sent, a filter removes URLs, file paths, `.localify` domains, and quoted -names. It matches patterns, so it can miss something in an unusual message. -Session replay is off by default, and you can turn it on in Settings. Builds -without `VITE_PUBLIC_POSTHOG_TOKEN` send nothing, and the CLI and daemon have no -telemetry. - -## Repository layout - -- `src/`: Rust library, CLI, daemon, DNS, TLS, routing, and project logic. -- `src-tauri/`: Tauri desktop shell and commands. -- `desktop-ui/`: React, Vite, and TanStack desktop interface. -- `apps/web/`: Next.js website, [localify.dev](https://localify.dev). See - [apps/web/README.md](apps/web/README.md). - -## Development - -Requirements: +The first run in a folder sets the project up. Localify picks a free port, registers a +domain such as `journal.localify`, allows it in Next.js `allowedDevOrigins` or Vite +`server.allowedHosts` when the project has that config file, and starts the `dev` +script with `PORT`, `HOST` and `LOCALIFY_URL` set. Then open `https://journal.localify`. -- Rust stable -- Node.js and pnpm -- macOS for the primary desktop development flow +In a monorepo, each app it detects gets its own domain (`web.journal.localify`, +`api.journal.localify`). A Git worktree gets its own domains and ports, next to the main +checkout. -Install JavaScript dependencies: +## Install -```bash -pnpm install -``` +**macOS app.** Download it from [localify.dev](https://localify.dev), or take the DMG +directly: . On first launch it asks +for your administrator password once, then sets up DNS, the certificate authority, the +background service and the `localify` command. The app updates itself. -Build the CLI: +**Command line, macOS (Apple Silicon) or Linux (x86_64):** ```bash -cargo build --bin localify +curl -fsSL https://localify.dev/install.sh | sh ``` -Run the desktop app with the development profile: - -```bash -pnpm tauri:dev -``` - -Run the website: - -```bash -pnpm web:dev -``` +The script checks the download's SHA-256, puts `localify` in `~/.local/bin`, then runs +`localify install`, which asks for your password once. Run it again to update. On Linux +you need systemd for the setup to run without root; read +[Localify on Linux](docs/linux.md) first. -## Quality checks +With a normal install (macOS, or Linux with systemd), nothing of Localify's runs as root +afterwards, and only your machine can reach it until you run `localify lan enable`. On +macOS, browsers trust Localify's HTTPS once you click Trust HTTPS in the app or run +`localify trust`. `localify uninstall` removes everything. -Rust changes must pass: +To build from source, see [CONTRIBUTING.md](CONTRIBUTING.md). -```bash -cargo fmt -cargo clippy -- -D warnings -cargo test -``` +## The commands you'll use -Desktop UI changes must also pass: +| Command | What it does | +| --- | --- | +| `localify dev [service]` | Start a service at its `.localify` URL. Add `--in-app` to run it in the desktop app's terminal, or `--detach` to run it in the background. | +| `localify services status` | Show what Localify started: running or not, PID, URL, port, since when, exit code. | +| `localify logs [-f]` | Print a service's output, from any folder. | +| `localify stop ` / `restart ` | Stop a service, or restart it where it ran. | +| `localify register --route "/=3000"` | Point a domain at any port, address or folder, without a project. | -```bash -pnpm run typecheck -``` +`localify status` checks the daemon, and `localify --help` lists everything else. The +[user guide](docs/README.md) covers projects, worktrees, routes, wildcards, [launch +profiles](docs/launch-profiles.md), [Docker](docs/docker.md) and troubleshooting. -Website changes must pass: +## Coding agents -```bash -pnpm web:typecheck -pnpm web:build -``` +`localify mcp` is an MCP server that gives Claude Code, Codex and Cursor every Localify +action as a tool: start a service and get its URL, read its output, restart it, clean up +a finished worktree. Each tool runs one `localify` command. `localify install` +and the app connect the agents they find; `localify agent install` does it again later. +See [Coding agents](docs/README.md#coding-agents). -## Documentation +## Localify Cloud -- [CLI reference](docs/README.md) -- [Architecture](docs/ARCHITECTURE.md) -- [Desktop development](docs/desktop.md) -- [Docker integration](docs/docker.md) -- [Launch profiles](docs/launch-profiles.md) -- [Linux setup](docs/linux.md) -- [Technical overview](docs/localify-technical-overview.md) +The paid part. [Public URLs](docs/README.md#public-urls) open a project at +`https://.localify.fyi`, behind a password, so you can reach it from your phone or +send it to someone. [Remote machines](docs/remote-machines.md) let you see, start and +stop the services of your other machines from the app. Both need Localify Cloud Pro: `localify +subscribe` starts it after a 7-day trial. Prices are on +[localify.dev/pricing](https://localify.dev/pricing). -Design notes for features that are not built yet: +## Privacy -- [Public URLs](docs/public-urls.md) -- [Remote machines](docs/remote-machines.md) +Official desktop builds send product analytics and error reports to PostHog. They send +explicit events only, with no autocapture. Analytics events never include project names, +domains, request logs or local paths. Before an error report leaves your Mac, a filter +removes URLs, file paths, `.localify` domains and quoted names. It matches patterns, so +it can miss something in an unusual message. Session replay is off unless you turn it on +in Settings. Builds without `VITE_PUBLIC_POSTHOG_TOKEN` send nothing, and the CLI and the +daemon have no telemetry. ## Contributing -Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) to get started, -including the [contributor license agreement](CLA.md) every contribution needs, -and the [code of conduct](CODE_OF_CONDUCT.md). To report a vulnerability, see -[SECURITY.md](SECURITY.md). - -## Acknowledgements - -Localify started as a fork of [Roxy](https://github.com/rbas/roxy) by -Martin Voldřich, which provides the original DNS, TLS, and reverse proxy -foundations. +Bug reports, fixes and docs are welcome. [CONTRIBUTING.md](CONTRIBUTING.md) explains how +to build, run and test Localify, and how pull requests work. Every contribution needs the +[contributor license agreement](CLA.md), and everyone follows the +[code of conduct](CODE_OF_CONDUCT.md). Report vulnerabilities privately, as +[SECURITY.md](SECURITY.md) explains. ## License -Localify is licensed under the [GNU Affero General Public License v3.0 -only](LICENSE). It derives from Roxy, whose code remains under the -[MIT license](LICENSE-MIT). +Localify is licensed under the [GNU Affero General Public License v3.0 only](LICENSE). +It started as a fork of [Roxy](https://github.com/rbas/roxy) by Martin Voldřich, which +provided the original DNS, TLS and reverse proxy foundations, and whose code remains +under the [MIT license](LICENSE-MIT). -The AGPL doesn't cover everything here. The Localify name and logo aren't -licensed, and neither is the media in `apps/web/public/`. `progresive-blur.tsx` is adapted from Skiper UI. -[NOTICE](NOTICE) has the details. +The AGPL doesn't cover everything here. The Localify name and logo aren't licensed, and +neither is the media in `apps/web/public/`. `progresive-blur.tsx` is adapted from Skiper +UI. [NOTICE](NOTICE) has the details. diff --git a/assets/logo-icon-2-white.svg b/assets/logo-icon-2-white.svg deleted file mode 100644 index 0bc621c5..00000000 --- a/assets/logo-icon-2-white.svg +++ /dev/null @@ -1,4 +0,0 @@ - - - - From 1396ea5056ba6783f404c35b33a34d061f6ec32b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?T=C3=A9o=20Goulois?= Date: Mon, 9 Nov 2026 18:51:17 +0100 Subject: [PATCH 2/2] docs: say where app updates install today --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5ed18315..3698af62 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ checkout. **macOS app.** Download it from [localify.dev](https://localify.dev), or take the DMG directly: . On first launch it asks for your administrator password once, then sets up DNS, the certificate authority, the -background service and the `localify` command. The app updates itself. +background service and the `localify` command. Updates install from Settings in the app. **Command line, macOS (Apple Silicon) or Linux (x86_64):**