🌐 CLI Instance Routing

Route Fiberwisecommands to local, default server, or remote instances with seamless configuration management

Overview

The Fiberwise CLI supports instance routing via the --to-instance parameter, allowing you to run agents on different Fiberwise instances. By default, agents run on your local machine instance for fastest performance.

💡 Instance Selection:
• Local Instance: --to-instance local (CLI default) - Your local machine
• Default Instance: --to-instance default - Your configured default server
• Named Instance: --to-instance "name" - Specific configured server

Available Instances

🏠 Local Instance (Default)

--to-instance local

Your local machine - Agents run directly on your development machine for fastest performance.

  • ✅ Fastest performance (optimized execution)
  • ✅ Full functionality available
  • ✅ No network dependencies
  • ✅ No configuration required
  • 🗄️ Uses local database and storage

🌐 Default Server Instance

--to-instance default

Your configured default Fiberwise server. Could be local development server, staging, production, or self-hosted remote.

  • 🌐 Runs on configured server
  • 🔑 Requires API authentication
  • 📋 Uses configuration set via fiber account add-config --set-default
  • 🚀 Flexible: can point to any environment

🌍 Named Server Instance

--to-instance "config-name"

A specific named Fiberwise server instance. Use this to target specific environments like staging, production, or team servers.

  • 🌐 Runs on named server
  • 🔐 Requires API authentication
  • ⚡ Network-dependent performance
  • 📊 Uses specific server configuration

Supported Commands

Command Local Support Remote Support Status
fiber activate ✅ Direct execution ✅ API routing Fully Implemented
fiber account list-providers ✅ Database query ✅ API endpoint Fully Implemented
fiber functions list ✅ Database query 🚧 Framework ready API Pending
fiber functions execute ✅ Direct execution 🚧 Framework ready API Pending
fiber functions list-agents ✅ Database query 🚧 Framework ready API Pending
fiber functions activate-multi ✅ Coordination engine 🚧 Framework ready API Pending

Configuration Setup

Example Configurations

Default Configuration (~/.fiberwise/configs/default.json)

{ "name": "default", "api_key": "c19fa728-ba66-4952-8df0-7dfa34cd09ef", "base_url": "http://127.0.0.1:8000", "created_at": "2025-08-09T13:27:22.737341", "updated_at": "2025-08-09T13:27:22.737365" }

Remote Configuration Example (~/.fiberwise/configs/production.json)

{ "name": "production", "api_key": "prod_api_key_here", "base_url": "https://api.fiberwise.ai", "created_at": "2025-08-09T10:00:00.000000", "updated_at": "2025-08-09T10:00:00.000000" }

Setup Commands

Basic Setup (Most Common)

# Add default configuration pointing to local server (after fiber setup) fiber account add-config \ --name "default" \ --api-key "fiber-platform-api-key" \ --base-url "http://127.0.0.1:8000" \ --set-default # Now --to-instance default will work fiber activate ./agent.py --to-instance default

Advanced Setup (Multiple Environments)

# Add production configuration fiber account add-config \ --name "production" \ --api-key "your-production-api-key" \ --base-url "https://your-server.com" # Add staging configuration and set as default fiber account add-config \ --name "staging" \ --api-key "your-staging-api-key" \ --base-url "https://staging.your-server.com" \ --set-default # List all configurations fiber account list-configs

Usage Examples

Agent Activation

# Local direct execution fiber activate ./agent.py --to-instance local # Server-based activation fiber activate ./agent.py --to-instance default # Remote server activation fiber activate ./agent.py --to-instance "production"

Provider Management

# List local providers fiber account list-providers --to-instance local # List remote providers fiber account list-providers --to-instance "production"

Function Management

# Local function listing fiber functions list --to-instance local # Remote function listing (framework ready) fiber functions list --to-instance "production"

Multi-Agent Coordination

# Local multi-agent activation fiber functions activate-multi agent1 agent2 \ --to-instance local # Remote multi-agent activation fiber functions activate-multi agent1 agent2 \ --to-instance "production"

Troubleshooting

🔒 Authentication Issues

Error: "Authentication failed. Check your API key."

Solution: Verify your API key in the configuration file and ensure it has the correct permissions.

# Test configuration fiber install test-connection --base-url "https://your-server.com"

🌐 Connection Issues

Error: "Connection error: Connection refused"

Solution: Ensure the target server is running and accessible. Check network connectivity and base URL.

⚙️ Configuration Issues

Error: "Configuration 'production' not found"

Solution: Add the required configuration using fiber account add-config.

🐛 Debug Mode

Use --verbose for detailed execution information:

fiber activate ./agent.py --to-instance "production" --verbose

API Authentication

API Key Format: Fiberwiseservers expect API keys with the api_ prefix. The CLI automatically handles this formatting.
# Correct API key format (automatic) Authorization: Bearer api_your-key-here Content-Type: application/json Accept: application/json

Architecture Benefits

🔄 Development Workflow

  1. Local Development: Use --to-instance local to run on your machine (fastest)
  2. Server Testing: Use --to-instance default to run on your development server
  3. Production Deployment: Use --to-instance "production" to run on production servers

🔧 Code Sharing

The instance routing system uses the fiberwise-sdk for maximum code reuse:

  • LocalClient for direct database access
  • RestClient for API calls
  • Consistent interface across all routing modes

📈 Scalability

  • Local Instance: Your development machine - fastest for iteration
  • Default Instance: Your default server - testing and integration
  • Named Instances: Production clusters, cloud deployments, team collaboration

🔮 Future Enhancements

  • Auto-discovery of execution context
  • Load balancing across instances
  • Intelligent response caching
  • Batch operations
  • Connection pooling

Quick Reference

Command Pattern Local Direct Local Server Remote Instance
Parameter --to-instance local --to-instance default --to-instance "prod"
Performance Fastest ⚡ Fast 🚀 Network-dependent 🌐
Use Case Local Development Default Server Named Server
Authentication None Required API Key Required API Key Required
Configuration None Required Default config file Named config file

Essential Commands

# Run on local machine (CLI default) fiber activate ./agent.py --verbose # Explicitly run on local machine (same as above) fiber activate ./agent.py --to-instance local --verbose # Run on your default server fiber activate ./agent.py --to-instance default --verbose # Run on production server fiber activate ./agent.py --to-instance "production" --verbose # Check providers across instances fiber account list-providers # Local instance fiber account list-providers --to-instance "production" # Production instance
✨ Result: This instance routing system provides a seamless transition from local development to production deployment while maintaining consistent CLI interface and maximizing code reuse through the fiberwise-sdk architecture.