Gen3 Admin Local Portable

Local Portable Networking

Start Here

1. Confirm this deployment uses the Local Portable profile (localPortable: true in the instance manifest, or GT3_LOCAL_PORTABLE=true in cluster config). The Models page shows a Local Portable networking active banner when the profile is on.
2. Use loopback URLs on the install host: https://127.0.0.1:3001 (Control Panel) and https://127.0.0.1:3002 (tenant app).
3. Share LAN URLs with peers on the same WiFi: https://<lan-ip>:3001 and https://<lan-ip>:3002. The current LAN IP appears on the banner and heals automatically after DHCP changes.
4. For self-hosted inference (Ollama), enter the GPU host LAN address in Models → Inference Providers—not loopback from the cluster’s perspective. See Ollama Host Setup.
5. After a network move, if discovery fails, check Stale inference provider URLs on the banner and update Ollama or other LAN provider base URLs to the new host IP.

Why this matters

Local Portable is for Linux portable hosts that roam between WiFi networks. Operators always keep loopback access on the machine; LAN peers use the current DHCP address. GT AI OS retargets ingress, TLS, and emailed login links without requiring a static IP or manual Helm edits after every network change.

This differs from server installs, which should use a fixed static IP. Roaming DHCP on a server-style install breaks bookmarks and provider URLs.

Details

Operator contract

Situation	URLs
Solo / offline on the install host	https://127.0.0.1:3001 and https://127.0.0.1:3002
On WiFi (same LAN as peers)	Loopback plus https://<lan-ip>:3001 and :3002
After DHCP move	LAN URLs update within ~30s (NetworkManager hook) or on the next timer tick; loopback unchanged

Install profile

Choose Local Portable for both Control Panel and Tenant App access in the Quick Installer / install-ai-os.sh wizard, or pass --local-portable to gt-ai-os-admin install.

Legacy aliases remain supported: wizard model laptop-dual, --laptop-networking, manifest key laptopNetworking, and GT3_LAPTOP_NETWORKING.

The installer autodetects the node LAN IP and enables automatic LAN autotarget heal (NetworkManager dispatcher plus a 30s systemd timer backup). Opt out with GT_AI_OS_LAN_AUTOTARGET=false.

Email and external IdP

Welcome and password-reset emails use loopback login URLs when Local Portable is enabled so links in the inbox work on the install host after DHCP roam.

Concern	Who manages it
External SAML/OIDC app registrations (Azure AD, Okta, …)	Operator — register redirect URIs for loopback (https://127.0.0.1:3001/oauth2/callback, :3002/...) and current LAN (https://<lan-ip>:3001/..., :3002/...)
Internal GT OIDC issuer URLs and loopback OAuth rewrite	Automatic — lan-autotarget + browser-edge

GT AI OS does not push redirect URI updates to third-party IdP consoles. After a DHCP move, update external IdP registrations if LAN peers authenticate through an upstream provider.

Manual heal commands

On the install host:

sudo gt-ai-os-admin lan-autotarget sync --namespace <namespace> --dry-run
sudo gt-ai-os-admin lan-autotarget sync --namespace <namespace> --yes
sudo gt-ai-os-admin lan-autotarget enable-daemon --namespace <namespace>

Validation

From the gt-ai-os repo on a host with cluster access:

export KUBECONFIG="$PWD/kubeconfig-rke2.yaml"
make validate-local-portable-networking

Stale inference provider URLs

When the LAN IP changes, the Control Panel banner lists providers whose saved base URL still points at the previous host. Open Models → Inference Providers, update each Base URL to the new LAN address (for Ollama: http://<new-lan-ip>:11434), then Test connection and Discover.

Limits (v1)

• Linux native RKE2 on the portable host only (not macOS/Multipass dev clusters)
• Requires one-time online install; not an offline-first/airgap bundle
• Guest WiFi client isolation and external IdP redirect URLs are operator concerns
• GT Managed / Cloudflare paths are unchanged

Related pages

• Models
• Ollama Host Setup
• QuickStart
• Advanced Management