io.github.info-arnav/unlocalhost

---

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

1. You add unlocalhost to your coding agent as an MCP server and sign in once with GitHub.
2. You tell the agent to deploy, and name who is allowed in.
3. Your agent pushes the code using your own git credentials. unlocalhost never holds write access to anything.
4. We clone read only, scan for committed secrets and refuse to continue if we find any, then build and run it.
5. 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      # fill it in
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.