Merge pull request #260 from gosuda/feature/update-docs

feat: add Portal Agent documentation and enhance wallet and ENS sections

Author: gosunuts

README.md

@@ -75,6 +75,24 @@ portal expose localhost:25565 --name minecraft --tcp
 portal expose 3000 --multi-hop-depth 3
 ```
 
+### Keep tunnels running with Portal Agent
+
+Use `portal agent run` when tunnels should keep running outside your terminal.
+It runs as a local OS service, keeps every tunnel in one TOML config alive, and
+provides a dashboard for relay and multi-hop management.
+
+```bash
+portal agent run --config config.toml
+portal agent dashboard --config config.toml
+portal agent restart
+portal agent stop
+
+# Foreground mode skips OS service installation.
+portal agent run --config config.toml --foreground
+```
+
+See [Portal Agent](docs/src/routes/portal-agent/+page.md) for the config format.
+
 ### Run your own relay
 
 ```bash
@@ -130,6 +148,8 @@ Tunnel clients include this registry by default. If you operate a public Portal
 
 - [CLI Reference](cmd/portal-tunnel/README.md)
 - [Concepts](docs/src/routes/concepts/+page.md)
+- [Portal Agent](docs/src/routes/portal-agent/+page.md)
+- [Wallet and ENS](docs/src/routes/wallet-and-ens/+page.md)
 - [Security Model](docs/src/routes/security-model/+page.md)
 - [Architecture](docs/src/routes/architecture/+page.md)
 - [Deployment](docs/src/routes/deployment/+page.md)

cmd/portal-tunnel/README.md

@@ -219,6 +219,10 @@ The agent service owns multiple tunnel definitions from one config file. The
 local control API binds to loopback and is authenticated with a token stored in
 the agent state directory.
 
+For the full agent workflow, control API, dashboard behavior, and wallet status
+auth details, see [Portal Agent](../../docs/src/routes/portal-agent/+page.md)
+and [Wallet and ENS](../../docs/src/routes/wallet-and-ens/+page.md).
+
 Useful commands:
 
 - `portal agent run` reads the platform default config path, installs or updates

docs/src/lib/nav.ts

@@ -56,8 +56,9 @@ export const guidesNavigation: NavSection[] = [
 		title: 'Guides',
 		items: [
 			{ title: 'Self-Hosting', href: '/self-hosting' },
+			{ title: 'Portal Agent', href: '/portal-agent' },
 			{ title: 'TCP/UDP Tunneling', href: '/tcp-udp-tunneling' },
-			{ title: 'SIWE Authentication', href: '/siwe-authentication' },
+			{ title: 'Wallet and ENS', href: '/wallet-and-ens' },
 			{ title: 'Deployment', href: '/deployment' },
 			{ title: 'Configuration', href: '/configuration' }
 		]

docs/src/routes/api-reference/+page.md

@@ -65,6 +65,11 @@ Admin clients authenticate with a wallet signature:
 5. Include the cookie in subsequent admin requests
 6. Sessions expire after 24 hours
 
+The local agent has its own loopback wallet auth endpoints under
+`/v1/agent/auth/*`. Agent wallet sessions can read `/v1/agent/status`; mutating
+agent actions require the bearer token stored in the agent state directory. See
+[Portal Agent](/portal-agent) for the local control API.
+
 ## Endpoint Summary
 
 ### SDK Endpoints
@@ -109,7 +114,7 @@ Admin clients authenticate with a wallet signature:
 | `GET` | `/healthz` | Health check | None |
 | `GET` | `/discovery` | Relay discovery | None |
 | `POST` | `/discovery/announce` | Relay discovery self-announce | Signed Descriptor |
-| `POST` | `/v1/sign` | Keyless TLS signing | None |
+| `POST` | `/v1/sign` | Keyless TLS signing | Access Token |
 | `GET` | `/thumbnail/{hostname}` | Cached thumbnail screenshot | None |
 | `GET` | `/tunnel/status` | Tunnel connection status | Access Token |
 
@@ -194,7 +199,11 @@ Submits this relay's signed descriptor to a bootstrap relay so registry-external
 
 ### `POST /v1/sign`
 
-Keyless TLS signing endpoint. Used by the relay's keyless TLS infrastructure. Only available when the API server is configured with a TLS private key.
+Keyless TLS signing endpoint. Used by the SDK-side tenant TLS server during the
+default stream handshake. Requests must include a valid lease access token in
+the `X-Portal-Access-Token` header.
+
+Only available when the API server is configured with a TLS private key.
 
 Returns `404 Not Found` if signing is not configured.
 

docs/src/routes/api-reference/sdk/+page.md

@@ -66,6 +66,20 @@ Get relay domain and protocol version information. Used by the SDK to verify rel
 |-------|------|-------------|
 | `protocol_version` | `string` | Protocol version (must match SDK version) |
 | `release_version` | `string` | Relay software release version |
+| `ens` | `object` | ENS gasless status for this relay |
+
+`ens` fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `enabled` | `bool` | ENS gasless automation is enabled for a non-local relay domain |
+| `verified` | `bool` | DNSSEC is active according to Portal and the last ENS sync succeeded |
+| `provider` | `string` | DNS provider used for automation |
+| `address` | `string` | Base-domain ENS address, usually the relay identity address |
+| `dnssec_state` | `string` | Provider DNSSEC state |
+| `ds_record` | `string` | DS record that may need registrar publication |
+| `message` | `string` | Provider-specific DNSSEC guidance |
+| `last_error` | `string` | Last ENS/DNS sync error |
 
 **Example:**
 
@@ -80,7 +94,14 @@ curl https://relay.example.com/sdk/domain
   "ok": true,
   "data": {
     "protocol_version": "5",
-    "release_version": "v2.1.5"
+    "release_version": "v2.1.5",
+    "ens": {
+      "enabled": true,
+      "verified": true,
+      "provider": "cloudflare",
+      "address": "0x1234567890abcdef1234567890abcdef12345678",
+      "dnssec_state": "active"
+    }
   }
 }
 ```

docs/src/routes/cli-reference/+page.md

@@ -206,8 +206,22 @@ portal agent restart
 | `portal agent restart` | Stop the current agent if present, install or update the service, and start it again |
 
 The local control API binds only to loopback and uses a token in the agent state
-directory. See [Configuration Reference](/configuration#configtoml) for the
-`config.toml` format.
+directory. See [Portal Agent](/portal-agent) for the workflow and
+[Configuration Reference](/configuration#configtoml) for the `config.toml`
+format.
+
+Agent flags:
+
+| Command | Flag | Default | Description |
+|---------|------|---------|-------------|
+| `portal agent run` | `--config` | platform default | Agent TOML config path |
+| `portal agent run` | `--foreground` | `false` | Run in the current process without installing the OS service |
+| `portal agent run` | `--service` | `false` | Internal service entrypoint used by the installed OS service |
+| `portal agent dashboard` | `--config` | platform default | Config path used for display and state-dir discovery |
+| `portal agent dashboard` | `--state-dir` | config/default | Agent state directory to attach to |
+| `portal agent stop` | `--config` | platform default | Config path used to resolve state dir and service name |
+| `portal agent stop` | `--state-dir` | config/default | Agent state directory to stop |
+| `portal agent restart` | `--config` | platform default | Config path used to reinstall and restart the service |
 
 ## `portal update`
 
@@ -253,6 +267,8 @@ Prints the installed version string and exits.
 ## Next Steps
 
 - [Getting Started](/getting-started): run your first tunnel
+- [Portal Agent](/portal-agent): run durable multi-tunnel services
+- [Wallet and ENS](/wallet-and-ens): understand wallet auth and ENS gasless DNS
 - [Concepts](/concepts): understand the relay and transport model
 - [TCP and UDP Tunneling](/tcp-udp-tunneling): raw TCP and UDP setup
 - [Deployment](/deployment): run your own relay server

docs/src/routes/concepts/+page.md

@@ -160,6 +160,10 @@ datagram authentication.
 
 Reusing the same identity path keeps the same tunnel identity across runs.
 
+Browser wallet login is separate from tunnel registration. Wallet sessions are
+used for relay admin access and optional local agent status access. See
+[Wallet and ENS](/wallet-and-ens) for the distinction.
+
 ## Domain Boundary
 
 The default stream path prevents the relay from safely injecting `robots.txt`,
@@ -170,5 +174,6 @@ separate wildcard tunnel domain instead of a brand or docs domain.
 ## Next Steps
 
 - [Getting Started](/getting-started): run your first tunnel
+- [Portal Agent](/portal-agent): run durable tunnel configs
 - [CLI Reference](/cli-reference): command and flag details
 - [Architecture](/architecture): protocol-level design notes

docs/src/routes/configuration/+page.md

@@ -198,7 +198,11 @@ Agent fields:
 | `state_dir` | Platform default state directory | Stores the local control endpoint token and runtime state |
 | `control_addr` | `127.0.0.1:4018` | Loopback-only local control API address |
 | `service_name` | `portal-agent` | OS service name |
-| `allowed_wallets` | empty | Wallet addresses allowed to sign in to the local agent UI; empty allows any wallet on the loopback UI |
+| `allowed_wallets` | empty | Wallet addresses allowed to read local agent status through wallet auth; empty allows any wallet on the loopback auth endpoint |
+
+The local agent dashboard and mutating control API calls use the bearer token in
+the agent state directory. Wallet-authenticated agent requests are read-only and
+can only read `/v1/agent/status`.
 
 Tunnel fields mirror `portal expose` flags:
 
@@ -212,9 +216,12 @@ Tunnel fields mirror `portal expose` flags:
 | `multi_hop` | string array | Ordered multi-hop relay path |
 | `multi_hop_depth` | int | Automatically select one multi-hop route with this depth |
 | `identity_path` | string | Tunnel identity JSON file path. When omitted, one tunnel uses the platform default `identity.json`; multiple tunnels use `<state-dir>/<tunnel-id>/identity.json` |
+| `identity_json` | string | Identity JSON payload; overrides `identity_path` contents and is persisted there when both are set |
 | `udp`, `udp_addr`, `tcp` | bool/string | UDP and raw TCP relay options |
 | `description`, `tags`, `owner`, `thumbnail`, `hide` | mixed | Lease metadata shown by relays |
 
+For a task-oriented walkthrough, see [Portal Agent](/portal-agent).
+
 ### `identity.json`
 
 Stores the secp256k1 identity used to sign tunnel sessions and relay descriptors. `portal expose` treats `--identity-path` as a direct JSON file path. `relay-server` treats `IDENTITY_PATH` as a state directory and stores this file at `IDENTITY_PATH/identity.json`.
@@ -245,6 +252,8 @@ Set `ACME_DNS_PROVIDER` (or `--acme-dns-provider`) to one of the values below to
 
 When this variable is empty the relay server falls back to manually supplied `fullchain.pem` and `privatekey.pem` files in `IDENTITY_PATH`.
 
+For ENS gasless behavior and wallet authentication details, see [Wallet and ENS](/wallet-and-ens).
+
 ### Cloudflare (`cloudflare`)
 
 | Variable | Required | Description |

docs/src/routes/deployment/+page.md

@@ -58,6 +58,9 @@ Set `ACME_DNS_PROVIDER` to one of:
 - `gcloud`
 - `route53`
 
+For a focused explanation of wallet auth and ENS gasless DNS behavior, see
+[Wallet and ENS](/wallet-and-ens).
+
 ### 3.2 Cloudflare setup
 
 #### Add domain to Cloudflare

docs/src/routes/getting-started/+page.md

@@ -134,6 +134,7 @@ verifies its SHA256 checksum, and replaces the current executable.
 ## Next Steps
 
 - [Concepts](/concepts): understand Portal's relay and transport model
+- [Portal Agent](/portal-agent): keep multiple tunnels running from config
 - [CLI Reference](/cli-reference): complete command and flag documentation
 - [TCP and UDP Tunneling](/tcp-udp-tunneling): raw TCP and UDP examples
 - [Deployment](/deployment): run your own public relay