@samitouri / QOSAMI-X402Tunnel-1
Code Commits Issues Pulls Sessions CI/CD
main
main
md 148 lines 5.18 KB
Rendered Raw
1 # Portal CLI
2
3 `cmd/portal-tunnel` builds the `portal` CLI. It exposes local services through
4 Portal relays without inbound firewall rules, port forwarding, or manual DNS
5 setup.
6
7 The relay owns transport, lease registration, routing, and relay policy. The
8 tunnel process owns local proxy behavior, routed HTTP policy, x402 route
9 payments, and tenant TLS termination for the default HTTPS stream path.
10
11 ## Quick Start
12
13 Install from GitHub release assets:
14
15 ```bash
16 curl -fsSL https://github.com/gosuda/portal-tunnel/releases/latest/download/install.sh | bash
17 portal expose 3000
18 ```
19
20 ```powershell
21 $ProgressPreference = 'SilentlyContinue'
22 irm https://github.com/gosuda/portal-tunnel/releases/latest/download/install.ps1 | iex
23 portal expose 3000
24 ```
25
26 If a relay publishes its own installer:
27
28 ```bash
29 curl -sSL https://portal.example.com/api/install.sh | bash
30 portal expose 3000 --relays https://portal.example.com --discovery=false
31 ```
32
33 ## Modes
34
35 Default HTTPS stream for most local web apps:
36
37 ```text
38 portal expose 3000 --name myapp
39 ```
40
41 Routed HTTP when one public URL should mount multiple local HTTP upstreams:
42
43 ```text
44 portal expose --name myapp \
45 --http-route /api=http://127.0.0.1:3001 \
46 --http-route /=http://127.0.0.1:5173
47 ```
48
49 Paid routed HTTP with Sui USDC x402:
50
51 ```text
52 portal expose --name paid-app \
53 --http-route "/paid=http://127.0.0.1:3001 GET:0.01" \
54 --http-route /=http://127.0.0.1:5173 \
55 --x402-pay-to 0x...
56 ```
57
58 Routed HTTP serves `/x402/client.js` and `/x402/prepare` on the tunnel origin so
59 an upstream browser frontend can run the same in-page Sui wallet payment flow as
60 the standalone payment app. Native clients should use `/x402/prepare` directly
61 and send the signed payload as `X-PAYMENT`. The tunnel still verifies and
62 settles payment before proxying the paid route. Paid routes use Sui mainnet by
63 default; add `--x402-testnet` to use Sui testnet.
64
65 Raw TCP and UDP:
66
67 ```text
68 portal expose localhost:25565 --name minecraft --tcp
69 portal expose localhost:8080 --udp --udp-addr localhost:19132 --name game
70 ```
71
72 ## Commands
73
74 ```text
75 portal expose [flags] <target>
76 portal expose [flags] --http-route "PATH=UPSTREAM [METHOD[,METHOD...]:USDC_AMOUNT]" [...]
77 portal list [flags]
78 portal agent run [flags]
79 portal agent dashboard [flags]
80 portal agent stop [flags]
81 portal agent restart [flags]
82 portal update
83 portal version
84 ```
85
86 Common `portal expose` flags:
87
88 ```text
89 --name Public hostname prefix; auto-generated when omitted
90 --relays Additional relay API URLs, comma-separated
91 --discovery Include registry relays and relay discovery expansion
92 --max-active-relays Maximum auto-selected relays
93 --multi-hop Ordered multi-hop relay API URLs, comma-separated
94 --multi-hop-depth Automatically select one multi-hop route with this hop count
95 --ban-mitm Ban relay when the MITM self-probe detects termination
96 --identity-path Identity JSON file path; created automatically when missing
97 --identity-json Identity JSON payload; overrides --identity-path when set
98 --description Service description metadata
99 --tags Service tags metadata, comma-separated
100 --thumbnail Service thumbnail URL metadata
101 --owner Service owner metadata
102 --hide Hide service from relay listing screens
103 --http-route HTTP route mapping in PATH=UPSTREAM [METHOD[,METHOD...]:USDC_AMOUNT] form
104 --x402-pay-to Sui USDC payment recipient address for this tunnel
105 --x402-testnet Use Sui testnet for tunnel x402 payments
106 --tcp Request a dedicated raw TCP port on the relay
107 --udp Enable public UDP relay
108 --udp-addr Local UDP target
109 --metrics-addr Optional host:port for Prometheus /metrics
110 ```
111
112 ## Agent
113
114 Use the agent for durable multi-tunnel operation from one config file:
115
116 ```text
117 portal agent run
118 portal agent dashboard
119 portal agent stop
120 portal agent restart
121 ```
122
123 The dashboard can edit basic tunnel settings, relays, and multi-hop routes. Add
124 Tunnel opens a small form for name, target or HTTP routes, x402 pay-to/testnet,
125 relays, discovery, and max active relays. After creation, routed HTTP paths,
126 route-level x402 amounts, payment network, and discovery mode are read-only in
127 the Settings pane. Edit `http_routes`, `x402_pay_to`, `x402_testnet`, or
128 `discovery` in TOML, then restart the agent or tunnel to change them.
129
130 ## Constraints
131
132 - A positional `<target>` cannot be combined with `--http-route`.
133 - `--http-route` cannot be combined with `--udp`.
134 - Route payment amounts are USDC values such as `0.01`, are part of
135 `--http-route`, and require `--x402-pay-to`; add `--x402-testnet` for Sui
136 testnet, otherwise payments use Sui mainnet.
137 - `--multi-hop` cannot be combined with `--multi-hop-depth`.
138 - Multi-hop currently supports only the default SNI TLS stream transport.
139 - `--tcp` and `--udp` require matching relay transport support.
140
141 ## More Docs
142
143 - [CLI Reference](../../docs/src/routes/cli-reference/+page.md)
144 - [Concepts](../../docs/src/routes/concepts/+page.md)
145 - [Configuration Reference](../../docs/src/routes/configuration/+page.md)
146 - [Portal Agent](../../docs/src/routes/portal-agent/+page.md)
147 - [Self Hosting](../../docs/src/routes/self-hosting/+page.md)
148 - [Wallet and ENS](../../docs/src/routes/wallet-and-ens/+page.md)