Skip to content

🌌 Stargate & P2P FAQ: The Full Picture

Context: This FAQ explores the integrated vision of Traylinx Stargate, the Traylinx CLI, and Stargate Station.

Q: How do I install Traylinx?

Answer: You have two installation paths, both resulting in the same software:

Path 1: CLI-First (Developer Flow)

This is the "Ubuntu minimal install" approach—start with the engine, add the cockpit if you want it.

# Step 1: Install CLI (via Homebrew or pipx)
brew install traylinx
# OR
pipx install traylinx-cli

# Step 2 (Optional): Add GUI Extension
traylinx install gui
# This prompts: "Would you like to install Stargate Station (GUI)? [y/N]"

Path 2: Station-Bundled (User Flow)

This is the "One-Click Installer" approach for non-developers—download a DMG/EXE/AppImage that includes EVERYTHING.

  1. Download: Stargate-Station-1.0.0-macos.dmg
  2. Install: Drag to Applications.
  3. Result: The installer automatically bundles the CLI inside the app. On first launch, it sets up ~/.traylinx/ for you.

Both paths result in the same setup: Traylinx CLI + Stargate Station GUI sharing the same identity and configuration.

Q: Can Stargate Station do everything the CLI can do?

Answer: Yes, for all things related to the Stargate Agent Network, the goal is 100% Parity.

CLI Command Stargate Station UI
traylinx stargate identity generate "Generate Identity" Button in Settings
traylinx stargate discover "Discover" Search Panel (Live List)
traylinx stargate call Interactive Chat Interface
traylinx stargate connect Toggle Switch for "Network Status"
traylinx run "Start Agent" Button

Q: What does "Integrated Stargate" in the CLI actually enable?

Answer: Integrating Stargate directly into the CLI (traylinx stargate ...) transforms the CLI from a simple API client into a P2P Node.

It enables: * Decentralized Setup: Run an agent from your laptop (traylinx run --stargate) and have it automatically punch through NAT (via libp2p) to join the global mesh. * Local Discovery: Run traylinx discover to see all other agents currently active in your local network or the global NATS/libp2p cluster. * Headless Orchestration: Script multi-agent workflows without needing a central server. Agent A calls Agent B via the CLI's internal P2P bridge.

Q: How does "Distribution" work on Stargate?

Answer: In a traditional app store, "Distribution" means uploading a binary to a server. On Stargate, Distribution means Manifest Propagation.

  1. Publish: You run traylinx publish. This sends your traylinx-agent.yaml to the Agent Registry (Centralized) or broadcasts it to the Stargate Gossip Network (Decentralized).
  2. Discovery: When an agent (or a user via Stargate Station) wants to find a service, they ask the network.
  3. Direct Connection: Once found, communication happens directly between peers. Stargate Station essentially becomes a "Browser for Agents," where each agent is a P2P destination rather than a URL.

Q: Can Stargate Station be used to set up the network?

Answer: Yes. While the CLI is optimized for speed and automation, Stargate Station provides a visual "Setup Wizard": * Visual key generation and backup. * One-click connection to bootstrap nodes. * Visual monitoring of NAT traversal status (are you reachable?). * Real-time logs of A2A calls.

Q: How does Stargate handle NAT traversal?

Answer: Stargate uses Circuit Relay v2 to enable agents behind NAT to communicate:

  1. Automatic NAT Detection: On startup, agents detect their network topology (public, private, symmetric NAT).
  2. Direct Connection First: Agents always attempt direct peer-to-peer connection first.
  3. Circuit Relay Fallback: If direct connection fails, agents automatically use a relay node.
  4. Connection Pooling: Connections are reused efficiently to minimize overhead.
  5. Health Monitoring: Relay nodes are continuously monitored; unhealthy relays are automatically avoided.

Example Flow: 

Agent A (Behind NAT) → Relay Node (Public IP) → Agent B (Behind NAT)

The relay node acts as a bridge, forwarding messages between agents that cannot connect directly. This is transparent to the application layer—your agent code doesn't need to know whether it's using a direct or relayed connection.

See NAT Traversal Guide for detailed configuration.

Q: What metrics are available for monitoring Stargate?

Answer: Stargate provides comprehensive metrics for monitoring P2P network health:

Metric Category Examples
Connection Metrics Active connections, connection attempts, failures
Relay Metrics Relay usage, relay health, relay latency
NAT Metrics NAT type distribution, traversal success rate
Message Metrics Messages sent/received, message latency, errors
Pool Metrics Pool size, connection reuse rate, evictions

Access metrics via: - CLI: traylinx stargate metrics - API: GET /metrics endpoint (Prometheus format) - Logs: Structured JSON logs with metric events

Q: How reliable is Circuit Relay v2?

Answer: Circuit Relay v2 is production-ready with the following reliability features:

  • Automatic Failover: If a relay node becomes unhealthy, agents automatically switch to another relay.
  • Connection Pooling: Connections are reused to minimize setup overhead and improve reliability.
  • Retry Logic: Failed connections are automatically retried with exponential backoff.
  • Health Monitoring: Relay nodes are continuously monitored with configurable health check intervals.
  • Graceful Degradation: If all relays are unavailable, agents fall back to NATS transport.

Test Results: 95.5% test pass rate with 193 passing tests covering all relay scenarios.

Q: Summarize the "Full Picture" of the Agentica ecosystem.

Answer: 1. The Blueprint: traylinx-agent-template (How to build an agent). 2. The Protocol: traylinx-stargate (How agents talk P2P). 3. The Engine: traylinx-cli (How developers manage agents). 4. The App Store/Browser: Stargate Station (How users find and use agents). 5. The Infrastructure: traylinx_core (The heavy-lifting services like Registry and Sentinel that provide stability to the decentralized mesh).