English Français العربية

io.github.info-arnav/unlocalhost

Official registry Developer tools

Deploy localhost to a private, authenticated link from your AI coding agent.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @unlocalhost/unlocalhost
Claude Code 
claude mcp add unlocalhost -e 'UNLOCALHOST_URL=<UNLOCALHOST_URL>' -e 'UNLOCALHOST_TOKEN=<your unlocalhost_token>' -- npx -y @unlocalhost/unlocalhost@0.1.1
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "unlocalhost": {
            "command": "npx",
            "args": [
                "-y",
                "@unlocalhost/unlocalhost@0.1.1"
            ],
            "env": {
                "UNLOCALHOST_URL": "<UNLOCALHOST_URL>",
                "UNLOCALHOST_TOKEN": "<your unlocalhost_token>"
            }
        }
    }
}

Environment variables

  • UNLOCALHOST_URL Base URL of the unlocalhost instance to talk to. Defaults to the hosted instance. Set this to point the tools at your own self hosted deployment.
  • UNLOCALHOST_TOKEN secret API token. Normally written by the unlocalhost_login tool after you approve the device in a browser, so you should not need to set this by hand.

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. unlocalhost
  2. The problem
  3. How it works
  4. What makes it different
  5. Quick start
  6. Self hosting
  7. Architecture
  8. Security
  9. Contributing
  10. Licence

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

  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 laptopNoYesYes
Private by defaultNoNoYes
Auth you have to writeAll of itAll of itNone
Runs on your own serverNoNoYes

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
PackageJob
webLanding page, sign in screens, docs
server/gatewayPublic API ingress, CORS, rate limiting, request ids
server/services/auth-gateOAuth, sessions, and the allowlist check on every request
server/services/control-planeApps, sharing, GitHub App, deploy pipeline
server/services/activatorWakes sleeping apps, puts idle ones back to sleep
server/services/mcp-serverThe unlocalhost npm package your agent talks to
server/sharedDatabase, 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.

Frequently asked questions

What is io.github.info-arnav/unlocalhost?

Deploy localhost to a private, authenticated link from your AI coding agent.

How do I install io.github.info-arnav/unlocalhost?

It runs on your machine. In Claude Code: claude mcp add unlocalhost -e 'UNLOCALHOST_URL=<UNLOCALHOST_URL>' -e 'UNLOCALHOST_TOKEN=<your unlocalhost_token>' -- npx -y @unlocalhost/unlocalhost@0.1.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.info-arnav/unlocalhost need an API key?

Yes. It expects UNLOCALHOST_TOKEN, which you set in its configuration.

Is io.github.info-arnav/unlocalhost open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.info-arnav/unlocalhost?

It is published by info-arnav. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.