unlocalhost
Turn localhost into a link only the people you name can open.
Sign in is built in, so you write no auth code and touch no servers.
Website · Docs · MIT licensed · Self hostable
The problem
Your coding agent can write the whole application. It cannot host it, because
hosting needs a server, a domain, a certificate, and a login system. So people
reach for whatever is fastest, and that is where things go wrong: a public URL
with no sign in, an API key committed by accident, or auth bolted on at the end
by someone who has never written auth.
unlocalhost closes that gap. You say one sentence to the agent you already have
open, and you get back a real URL with a guest list in front of it.
you deploy this and let sarah@gmail.com in
agent pushed your code to a private repo
agent building
agent live at sarahs-todo.unlocalhost.tech
agent sarah@gmail.com can sign in and open it
How it works
- You add unlocalhost to your coding agent as an MCP server and sign in once
with GitHub.
- You tell the agent to deploy, and name who is allowed in.
- Your agent pushes the code using your own git credentials. unlocalhost
never holds write access to anything.
- We clone read only, scan for committed secrets and refuse to continue if we
find any, then build and run it.
- Visitors sign in with GitHub or Google. Their verified email is checked
against the guest list before the request ever reaches your app.
What makes it different
| Tunnel (ngrok) | Platform (Vercel) | unlocalhost |
|---|
| Survives closing laptop | No | Yes | Yes |
| Private by default | No | No | Yes |
| Auth you have to write | All of it | All of it | None |
| Runs on your own server | No | No | Yes |
Quick start
claude mcp add unlocalhost -- npx -y @unlocalhost/unlocalhost
Or in any MCP client config:
{
"mcpServers": {
"unlocalhost": {
"command": "npx",
"args": ["-y", "@unlocalhost/unlocalhost"]
}
}
}
Then ask your agent to sign in to unlocalhost, and deploy.
Self hosting
The hosted service runs this exact code. Nothing is held back, there is no
phone home, and no license check.
git clone https://github.com/info-arnav/unlocalhost.git
cd unlocalhost/deploy
cp .env.example .env
docker compose --env-file .env run --rm migrate
docker compose --env-file .env up -d
You need a domain with wildcard DNS, a DNS provider API token for wildcard TLS,
a GitHub App, and a Google OAuth client. The full walkthrough is in
docs/server-setup.md.
Architecture
internet :443 → Caddy → auth-gate /verify → activator → Dokku → your app
| Package | Job |
|---|
web | Landing page, sign in screens, docs |
server/gateway | Public API ingress, CORS, rate limiting, request ids |
server/services/auth-gate | OAuth, sessions, and the allowlist check on every request |
server/services/control-plane | Apps, sharing, GitHub App, deploy pipeline |
server/services/activator | Wakes sleeping apps, puts idle ones back to sleep |
server/services/mcp-server | The unlocalhost npm package your agent talks to |
server/shared | Database, logging, crypto, errors, sessions |
Borrowed rather than built: Dokku and
Nixpacks turn a repository into a running container,
Caddy handles wildcard TLS. The novel part is small
on purpose.
Security
- Apps are private until you name someone. Removing them revokes access at once.
- Every deploy is scanned for committed secrets and refused if any are found.
- Sign in is enforced at the edge, before a request reaches your app.
- Environment variables are encrypted at rest with AES 256 GCM.
- We hold read only access, and only to repositories you pick.
Found a vulnerability? Please follow SECURITY.md rather than
opening a public issue.
Contributing
Read CONTRIBUTING.md first. In short: every backend module
follows routes → controller → service → repository, code carries no comments,
and there are no test files. Verification is done by running things.
Licence
MIT. See LICENSE.