Pick the guide that matches you. Each takes five minutes or less.
Install, sign in, share a sandbox and connect Claude.
Developer · 3 mincatflap login, catflap enter, and the JSON for your client.
Admin · 4 minAn API key, a systemd unit and how to revoke it.
Get the command line from the download page, then:
$ catflap login $ catflap enter --name weather -- npx -y @mcp/weather
The tunnel is created the first time you use a name. Its address is https://catflap.uni-obuda.hu/s/USER/weather/mcp; your dashboard has the client config for Claude, Cursor, VS Code and others.
/etc/catflap.env as CATFLAP_KEY=cfk_…, readable only by the service user.[Service] EnvironmentFile=/etc/catflap.env ExecStart=/usr/local/bin/catflap --gateway https://catflap.uni-obuda.hu enter --name lab -- /opt/mcp/server Restart=always
To switch the machine off, revoke its key on the API keys page: its tunnels go offline at once and can't reconnect.
Each tunnel's page on your dashboard has the exact steps and the config for your app. In short:
Settings → Connectors → Add custom connector. Paste the tunnel's address, press Connect, sign in with Catflap and press Allow.
Add a custom connector (remote MCP server) with the address and OAuth. Your plan may need developer mode switched on.
Add the address to mcp.json (Cursor) or .vscode/mcp.json (VS Code). They open the sign-in page on first use.
Use the tunnel's client token as a header: Authorization: Bearer cft_…. Anyone with the token can use the tunnel, so replace it when in doubt.
The same words appear in the app, on the website and in the tray.
| Status | What it means | What to do |
|---|---|---|
| Online | Your AI can use it now. | Nothing. |
| Connecting | Catflap is starting what you share and connecting to the gateway. | Wait a few seconds. Still connecting after a minute? Check your internet connection. |
| Reconnecting | The connection dropped. Catflap keeps trying, and your AI waits meanwhile. | Wait. Still reconnecting after a minute? Check your internet connection. |
| Offline | Waiting for your computer: Catflap isn't running there, or sharing was stopped. | Open Catflap on that computer and press Start. |
| Failed | What you share stopped with an error, such as a missing tool. | Open the share in the Catflap app: it says what went wrong and how to fix it. |
| Stopped | You stopped sharing. The address stays reserved for you. | Press Share again to bring it back. |
| Paused | Sharing is paused from the tray. The address stays reserved for you. | Press Resume to share it again. |
Open the tunnel on your dashboard and press Test connection. If the test works, remove the connector in your AI app and add it again, then sign in. If you use a client token, check that it is the current one.
Only you sign in. AI apps connect with your Catflap account (OAuth) and only after you press Allow. You can revoke an app on any tunnel's page.
Tokens and keys are revocable. A client token is a password for one tunnel; replace it to lock old copies out. Revoke an API key and its machine disconnects at once.
Nothing is stored. The gateway passes requests between your AI and your computer. It keeps a short list of recent calls (tool names and timings) so you can see what happened, not their content.
You stay in control. Stop sharing in the app, or quit it, and the tunnel is offline. Deleting a tunnel on the dashboard ends its address and token for good.
Everything the app does, for servers and scripts.
| Command | What it does |
|---|---|
catflap login | Sign in through the browser. You stay signed in. |
catflap login --device | Sign in with a code you confirm on another device, on a machine without a browser. |
catflap enter --name NAME -- CMD | Share any MCP server under a tunnel name. |
catflap enter --name NAME --sandbox | Share the Podman sandbox (set it up in the app). |
catflap enter | Share this computer's files and shell (fs_list, fs_read, fs_write, shell_exec). |
catflap --gateway URL … | Use another gateway than the one you signed in to, e.g. https://catflap.uni-obuda.hu. |
catflap whoami | Show who is signed in. |
catflap logout | Sign out and forget the stored login. |
CATFLAP_KEY=cfk_… | Use an API key instead of a login (unattended machines). |
Still stuck? Write to the team running this server. Say what you tried and add the diagnostics from the app's Help menu, so we can help faster. Found a bug in Catflap itself? Report it to the open-source project.