---
name: localhost-run
description: This is a SKILL.md file for the localhost.run agent. It must be placed in the skill directory (e.g., .opencode/skills/localhost-run/ or .claude/skills/localhost-run/) for the agent to load it correctly. The file contains instructions for connecting a local app via a tunnel so it is reachable on the internet at a given subdomain.
---

# localhost-run

## What this skill does

This skill connects a local application to the internet through a tunnel, making it reachable at a specified subdomain (e.g., localhost.run/my-subdomain). It handles the SSH tunnel setup and verification so that the agent can interact with the local app over HTTPS.

## When to use it

Use this skill when you need to expose a local development server (e.g., a web app, API, or database) to the internet via the localhost.run tunnel. It is particularly useful for:

- Testing local applications in a shared environment
- Running CI/CD pipelines that require external access
- Debugging remote issues by connecting to a local instance

## Preconditions

Before connecting the tunnel:

1. Check local access using `curl` or a similar tool. Example:
   ```bash
   curl -sS -o /dev/null -w "%{http_code}" http://127.0.0.1:PORT/
   ```
2. If local access does not work (e.g., empty reply, connection refused, or `000` status), debug the issue with the user. Check:
   - Whether the server process is running
   - Whether the server is holding the correct port
   - Server logs for errors (e.g., `OSError: [Errno 98] Address already in use`, connection failures)
3. Only start the tunnel once local access is ready (HTTP status returns `200` or the appropriate success code for the app).

## Setup

1. Ensure the local application is running on localhost:PORT (the PORT should be set in your environment).
2. Place this SKILL.md file in your skill directory:
   - OpenCode: .opencode/skills/localhost-run/SKILL.md
   - Claude Code: .claude/skills/localhost-run/SKILL.md
   - Other agents: .agents/skills/localhost-run/SKILL.md
3. The agent will automatically load this file when it needs to connect the tunnel.

## Tunnel command

Run the SSH tunnel in the background with a clean TTY (`-n`). This is a blocking command — append `&` or wrap with `nohup` / `screen` / `autossh` so it stays alive:

```bash
ssh -n -o ServerAliveInterval=60 -o ExitOnForwardFailure=yes -o StrictHostKeyChecking=accept-new \
  -R SUBDOMAIN:80:localhost:PORT plan@localhost.run -- --output json
```

- `-n` keeps the TTY clean when running in the background.
- `plan@localhost.run` connects as the `plan` user.
- `StrictHostKeyChecking=accept-new` (or `no`) handles host key verification automatically.
- `SUBDOMAIN` is the full hostname the user provides (e.g., `my-app.lhr.rocks` or `example.com`). Pass it directly to `-R SUBDOMAIN:80:localhost:PORT`. Free `.lhr.rocks` subdomains and custom domains use the same SSH command format.
- Run with `nohup ... &` in the background.

## Domain setup

If you need a custom domain, log in at https://admin.localhost.run/ to set it up on your account. `.lhr.rocks` subdomains require no DNS; own domains require DNS configuration (see https://localhost.run/docs/custom-domains).

## Verification

After the skill runs, verify the tunnel is active by checking the HTTP status against the subdomain:

```bash
curl -sS -o /dev/null -w "%{http_code}" https://SUBDOMAIN/
```

Expected response: `200` (or the appropriate status code for your app). If using a custom domain, verify TLS termination is working (see `https://admin.localhost.run/` for custom domain setup).

## Troubleshooting

If the user reports issues (tunnel not working, empty reply, or connection refused):

- Check whether the tunnel process is running (`ps aux | grep localhost.run`).
- Check the server process (`ps aux | grep "python3 -m http.server"` or equivalent).
- Check server logs (`/tmp/http_server.log` or relevant output).
- Only restart the tunnel once local access (`http://127.0.0.1:PORT/`) is confirmed working (`200`).
- Run a test request to the local service (`curl http://127.0.0.1:PORT/`) to ensure it is ready to receive tunnel traffic before starting or restarting the SSH connection.

## Notes

- The name field must match the parent directory name exactly.
- The description should be specific enough for the agent to recognize when to activate the skill.
- Source reference: https://localhost.run/SKILL.md
- Full documentation: https://localhost.run/docs/
- The user requires an SSH key configured with their localhost.run account. If the tunnel command directs them to upload one, help them create an SSH key pair (`ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519`) or choose an existing one, then upload their public key (`~/.ssh/id_ed25519.pub`) to their localhost.run account at https://admin.localhost.run.
- This skill follows the open standard SKILL.md format used by Claude Code, Codex CLI, OpenCode, and other AI agent platforms.