Remote access

Homestead never opens ports to the internet by itself. To use it away from home, on your phone or from an agent on another machine, put one of these in front of it. The project recommends them in this order.

The web app runs separately for now

On main, the server answers the API on port 8080 but doesn't serve the web app yet: opening http://localhost:8080/ returns 501 not_implemented (webdist is still empty). Until that lands, run the web app's development server from the same checkout, as in Quick start. It listens on http://localhost:5173 and forwards /api, /media and /mcp to the server.

Pick a way in

Tailscale

The simplest choice, and it works for the phone app too. Your devices join a private network, and nothing is exposed to the public internet.

1. Install Tailscale on the Homestead machine and on each phone or computer that should reach it, following Tailscale’s own documentation.

2. Reach Homestead at the machine’s Tailscale address (the API and phone app use port 8080), or at a Tailscale HTTPS name if you’ve set one up. The agent examples in the app’s docs use a name like https://homestead.example.ts.net.

3. Set HOMESTEAD_BASE_URL to that address so links and QR codes carry it.

Cloudflare Tunnel

A tunnel connects out from your machine to Cloudflare and serves Homestead at a name you own, with no open ports.

1. Create a tunnel by following Cloudflare’s documentation, pointing it at http://localhost:8080 on the Homestead machine.

2. Set HOMESTEAD_BASE_URL to the tunnel’s public https:// address.

Caddy (reverse proxy)

A reverse proxy with TLS on your own domain. The repository has a ready example in deploy/Caddyfile.example:

home.example.com {
  encode zstd gzip

  request_body {
    max_size 50MB
  }

  reverse_proxy homestead:8080

  header {
    Strict-Transport-Security "max-age=31536000"
  }
}

1. Replace home.example.com with your own name and point its DNS records at the machine.

2. Set HOMESTEAD_BASE_URL=https://home.example.com on the Homestead container.

3. With Compose, start the bundled Caddy service:

   docker compose -f deploy/compose.yaml --profile caddy up -d --build

Keep the 50 MB body limit: it matches Homestead’s own upload limit. Caddy obtains and renews certificates on its own. The Docker Compose guide has the details.

Set the base URL

HOMESTEAD_BASE_URL is the public address of your Homestead, without a trailing slash, for example https://home.example.com. Set it whenever Homestead sits behind a proxy or tunnel. It is used for:

• share links and their QR codes,
• invite links, and the server address inside phone pairing QR codes,
• the MCP URL in agent setup snippets,
• signed media URLs.

It also changes how the server treats browsers. With an https:// base URL, sign-in cookies are marked Secure, and writes from the web app must come from that exact origin. That’s what you want behind TLS, but it means the base URL must match the address people actually type. Without it, Homestead uses the address from each request.

With docker run, pass it with -e:

docker run -d --name homestead -p 8080:8080 -v homestead-data:/data -e HOMESTEAD_BASE_URL=https://home.example.com homestead

Trusted proxies

HOMESTEAD_TRUSTED_PROXIES takes a comma-separated list of CIDRs, such as 172.18.0.0/16, that are allowed to set X-Forwarded-* headers. It’s empty by default. Each entry must be a valid CIDR or the server refuses to start.

Note

On main the server validates this setting, but it takes the client address from the direct connection and doesn’t read X-Forwarded-For yet. Behind a proxy, per-IP limits such as the login limit (10 a minute) count the proxy’s address.

Use TLS when you expose it

If Homestead is reachable from the internet, use HTTPS. Session cookies are only Secure over HTTPS, and while media URLs are signed, everything else rides on the connection. Nothing in Homestead phones home, so the only traffic is yours.

Check that it worked

From a machine outside your home network (or a phone with Wi-Fi off), ask the health endpoint at your public address:

curl https://home.example.com/api/v1/health

Then sign in in a browser and add a note to someone. If saving fails, recheck the base URL.