mirror of
https://github.com/nearai/ironclaw.git
synced 2026-09-02 23:56:24 +08:00
101 lines
2.6 KiB
Plaintext
101 lines
2.6 KiB
Plaintext
---
|
|
title: "Setup a Tunnel"
|
|
description: "Expose your local agent to the internet"
|
|
---
|
|
|
|
A tunnel exposes your local IronClaw agent to the internet. You need it for webhook-based channels and for instant message delivery where polling is not desired.
|
|
|
|
<Note>
|
|
If you haven't set up your agent yet, follow our [Quickstart guide](./quickstart)
|
|
</Note>
|
|
|
|
---
|
|
|
|
## Configure
|
|
|
|
Configure a tunnel through the onboarding command:
|
|
|
|
```bash
|
|
ironclaw onboard --channels-only
|
|
```
|
|
|
|
### ngrok
|
|
|
|
`ngrok` is a managed tunnel service with a minimal setup, ideal if you are just starting with `ironclaw`. To use it, you will need to get an auth token from the [ngrok dashboard](https://dashboard.ngrok.com/get-started/your-authtoken)
|
|
|
|
### Cloudflare
|
|
|
|
`Cloudflare Tunnel` connects your local service to Cloudflare via outbound-only connections from `cloudflared`.
|
|
|
|
Use it when you already run Cloudflare Zero Trust or want a production-style ingress layer. Before setup:
|
|
|
|
Install `cloudflared`:
|
|
|
|
<Tabs>
|
|
<Tab title="macOS">
|
|
|
|
```bash
|
|
brew install cloudflared
|
|
```
|
|
|
|
</Tab>
|
|
<Tab title="Ubuntu">
|
|
|
|
[Cloudflare package install guide](https://pkg.cloudflare.com/).
|
|
|
|
</Tab>
|
|
<Tab title="Other">
|
|
|
|
[Cloudflare Tunnel downloads page](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/).
|
|
|
|
</Tab>
|
|
</Tabs>
|
|
|
|
Then, create a tunnel in the [Cloudflare dashboard](https://dash.cloudflare.com) under `Zero Trust > Networks > Connectors` follow the instructions to get the tunnel token.
|
|
|
|
|
|
### Tailscale
|
|
|
|
`Tailscale` is a WireGuard-based private mesh network for your devices (your tailnet). Use it when your team already relies on Tailscale networking.
|
|
|
|
### Custom
|
|
|
|
Use this option when you want full control over the tunnel command and process.
|
|
|
|
Provide a shell command with placeholders:
|
|
|
|
- `{port}` for IronClaw's local port
|
|
- `{host}` for IronClaw's local host
|
|
|
|
Example:
|
|
|
|
```bash
|
|
bore local {port} --to bore.pub
|
|
```
|
|
|
|
### Static URL
|
|
|
|
Use this option when the tunnel is managed outside IronClaw and you already have a stable public URL.
|
|
|
|
IronClaw will use that URL directly and will not start or manage any tunnel process.
|
|
|
|
---
|
|
|
|
## Which option to pick
|
|
|
|
| Option | Best for |
|
|
|---|---|
|
|
| `ngrok` | quickest setup, local development |
|
|
| `Cloudflare` | production-style setup with Cloudflare stack |
|
|
| `Tailscale` | teams already using Tailscale networking |
|
|
| `Custom` | custom tunnel tooling and command control |
|
|
| `Static URL` | externally managed ingress with fixed public URL |
|
|
|
|
---
|
|
|
|
## Security notes
|
|
|
|
- Treat tunnel tokens and URLs as sensitive credentials.
|
|
- Prefer short-lived or rotated tokens where possible.
|
|
- If exposing public endpoints, apply channel-level auth and least-privilege access.
|