Skip to content

🛠️ LOCAL DEVELOPMENT OPTIONS

Context: This FAQ covers how to run the Traylinx network infrastructure (Registry, Router, Subscriptions) on your local machine while connecting to the production authentication service (Traylinx Sentinel).

Q: What possibilities do I have to run the Traylinx network on my local machine?

Answer: Since you can use the production Traylinx Sentinel (Auth) and Switch AI APIs, you only need to run the "Infrastructure Plane" services locally. This creates a Hybrid Local Network.

You have 3 main possibilities, ranked by complexity and use case:

1. Docker Compose (The "One-Click" Solution)

Best for: Running the full network to test agent interactions without touching code.

  • Concept: A single root-level docker-compose.yml orchestrates all services (Registry, Router, Subscription) and their databases.
  • Pros:
    • ✅ Simple: Start everything with docker-compose up.
    • ✅ Isolated: Zero networking conflicts; services find each other by container name.
  • Cons:
    • ❌ Slow Iteration: Changing code requires rebuilding container images.
  • Prerequisites: Docker Desktop.

2. Manual / Script Mode (The "Developer" Solution)

Best for: Active development where you need "Hot-Reloading".

  • Concept: You run the databases (Postgres/Redis) via Docker, but run the Python applications directly on "bare metal" using poetry run uvicorn ... --reload.
  • Pros:
    • ✅ Fastest Feedback Loop: Save a file, and the server restarts instantly.
    • ✅ Native Debugging: Easier to attach debuggers in VS Code.
  • Cons:
    • ❌ Messy: Requires multiple terminal tabs (one for each service).
    • ❌ Manual Config: You must manually ensure environment variables are set in every tab.

3. Local Kubernetes (The "Production Parity" Solution)

Best for: Testing deployment manifests, ingress controllers, or scaling logic.

  • Concept: deploying the services into a local cluster like Kind, k3d, or Docker Desktop Kubernetes.
  • Pros:
    • ✅ Realism: Tests exactly how services behave in production (DNS, Service Discovery, Load Balancing).
    • ✅ Scalability: Can simulate running 5 replicas of the Router Agent.
  • Cons:
    • ❌ Heavy Lift: Requires creating/maintaining Helm charts or K8s manifests (which don't fully exist yet).
    • ❌ Slow: The Code → Build → Push → Deploy loop is the slowest of all options.

💡 Recommendation

  • For Feature Development: Use Option 2 (Manual/Script).
  • For Integration Testing: Use Option 1 (Docker Compose).

Q: Which services do I actually need for the Traylinx Core Network?

Answer: The Traylinx Core Network is the minimal infrastructure needed for agents to discover, communicate, and publish events. It does not include the consumer applications (like the Traylinx frontend, payments, or AI Studio).

✅ Required Services (Run Locally)

Service Port Purpose
Agent Registry 8000 The "Phone Book" — agent discovery & capabilities
Router Agent 8080 Request routing & event fan-out
Subscription Service 8001 Pub/Sub event subscriptions

✅ Required Services (Use Production API)

Service API URL Purpose
Traylinx Sentinel api.makakoo.com/ma-authentication-ms A2A authentication, Agent Secret Token
Switch AI api.makakoo.com/ma-llm-proxy-ms LLM routing (if Cortex needs it)

⚙️ Optional (Depends on Use Case)

Service Purpose When Needed
Traylinx Cortex Memory, LLM routing for agents Only if your agents use memory/AI features

❌ Not Part of Core Network (Separate Consumer Apps)

These are applications that use the Traylinx network, but are not required to run it:

  • metrics_workspace_ms (Wallets, Organizations, Projects)
  • makakoo_payments_ms (Stripe/Coinbase payments)
  • ai_studio_ms (Agent Studio, MCP Registry)
  • github_services_ms (GitHub forking)
  • search_engines_ms (Web search)
  • traylinx frontend (React dashboard)

📋 Minimal Local Setup Summary

# 1. Set environment variables (create .env in each service or export)
export TRAYLINX_CLIENT_ID="your-client-id"
export TRAYLINX_CLIENT_SECRET="your-client-secret"
export TRAYLINX_AGENT_USER_ID="your-agent-uuid"
export TRAYLINX_API_BASE_URL="https://api.makakoo.com/ma-authentication-ms/v1/api"

# 2. Start databases (in traylinx_core/)
cd traylinx_agent_registry && docker-compose up -d postgres redis
cd ../traylinx_subscription_service && docker-compose up -d postgres

# 3. Run services (3 terminal tabs)
# Tab 1: Registry
cd traylinx_core/traylinx_agent_registry
poetry run uvicorn app.main:app --port 8000 --reload

# Tab 2: Subscriptions
cd traylinx_core/traylinx_subscription_service
poetry run uvicorn app.main:app --port 8001 --reload

# Tab 3: Router
cd traylinx_core/traylinx_router_agent
poetry run uvicorn app.main:app --port 8080 --reload

# 4. Verify
curl http://localhost:8000/health  # Registry
curl http://localhost:8001/health  # Subscriptions
curl http://localhost:8080/ready   # Router