🎯 ft-sovx - Front Terrain Sovereign Infrastructure CLI

A hybrid Node.js + Python package that auto-boots a FastAPI backend server.

📦 What's Bundled?

When you install ft-sovx, you get:

• ✅ Node.js CLI (bin/index.js) - Command-line interface
• ✅ Python Backend (backend/main.py) - FastAPI server with Uvicorn
• ✅ Python Dependencies - Auto-installed via postinstall script

🚀 Quick Start

Step 1: Install Globally

npm install -g ft-sovx

Step 2: Setup Python Dependencies

ft-sovx setup

This installs all required Python packages from backend/requirements.txt.

Step 3: Boot the Sovereign Core

ft-sovx start

The CLI will automatically:

• ✔️ Detect the bundled Python backend location
• ✔️ Check if FastAPI server is already running
• ✔️ Launch Uvicorn server in background (if not running)
• ✔️ Connect to the control panel at https://ft-sovx.web.app

📍 How Path Resolution Works

The CLI uses automatic path detection:

// Resolves to the installed npm package location
const __dirname = dirname(fileURLToPath(import.meta.url));
const pathToPythonBackend = join(__dirname, '..', 'backend');

This means you can run ft-sovx start from any directory - the Python server will always boot from the correct bundled location!

🎮 Available Commands

Account Management

ft-sovx signup

Register a new account and receive X-FT-Sovereign-Key via email

Interactive registration flow:

• Enter company name, email, password
• Firebase account created in cloud
• X-FT-Sovereign-Key generated and sent via email
• Check your inbox for the activation email
• Use the key from email with ft-sovx auth

ft-sovx signup

ft-sovx auth

Authenticate with existing credentials

# Login with email and sovereign key
ft-sovx auth

# Logout and remove credentials
ft-sovx auth --logout

Supports:

• Email/password authentication via Firebase
• Sovereign key verification
• Session management
• Logout option with --logout flag

ft-sovx iam

Display authenticated client identity and access details

# Show all details
ft-sovx iam

# Show specific field
ft-sovx iam --key    # Display sovereign key only
ft-sovx iam --email  # Display email only
ft-sovx iam --uid    # Display user ID only
ft-sovx iam --json   # Output as JSON

Infrastructure Management

ft-sovx start

Initialize and boot Sovereign Core Engine

ft-sovx start

Auto-detects and boots:

• FastAPI backend server
• Nginx cluster balancer
• Security gateways
• Telemetry tracking

ft-sovx stop

Gracefully shutdown the sovereign node

ft-sovx stop

Sends SIGTERM to active gateway nodes.

ft-sovx status

Check infrastructure telemetry and health

ft-sovx status

Displays:

• Network cluster proxy status
• Encryption vault pipeline status
• Data anonymization logic status
• Backend health check

ft-sovx configure

Show system configuration and deployment settings

ft-sovx configure

Shows:

• Deployment mode (local/cloud)
• Backend URL
• Config file path
• System information (OS, Node.js, Python)
• Authentication status
• Backend health status

Package Information

ft-sovx about

Display package information and metadata

ft-sovx about

Shows:

• Package name, version, description
• Author and license information
• NPM registry details
• Node.js requirements
• Keywords
• Latest version available on npm
• Published date
• Update notifications if available

🔑 Authentication Flow

First Time Setup

# 1. Register new account
ft-sovx signup
# → Enter: Company Name, Email, Password
# → Firebase account created in cloud
# → Check your email for X-FT-Sovereign-Key

# 2. Authenticate with received key
ft-sovx auth
# → Enter: Email and Password
# → Paste: X-FT-Sovereign-Key received via email
# → Session: Active credentials stored locally

# 3. Boot infrastructure
ft-sovx start
# → Backend server boots automatically
# → Infrastructure ready at http://127.0.0.1:8000

# 4. View your details
ft-sovx iam

Returning Users

# Login with existing credentials
ft-sovx auth
# → Enter: Email and Password
# → Paste: X-FT-Sovereign-Key from your email
# → Session: Active credentials stored locally

# Boot infrastructure
ft-sovx start

Logout

# Remove stored credentials
ft-sovx auth --logout
# → Credentials cleared from ~/.ft-sovx/config.json
# → Run "ft-sovx auth" to login again

🔐 Credentials & Configuration

Local Storage

All credentials are stored securely in your home directory:

~/.ft-sovx/config.json

Contains:

{
  "sovereign_key": "ft_sovx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "email": "[email protected]",
  "company_name": "Your Company",
  "password_hash": "sha256_hash_of_password",
  "uid": "user_unique_identifier",
  "authenticated_at": "2026-05-29T10:30:00.000Z"
}

Security

• ✔️ Sovereign key stored locally (never sent to third parties)
• ✔️ Password stored as SHA256 hash only
• ✔️ File permissions restricted to user only
• ✔️ Authentication persists across sessions
• ✔️ Logout completely removes credentials

🔧 Architecture

~/.npm/[email protected]/
├── bin/
│   └── index.js          ← Node.js CLI entry point
├── backend/
│   ├── main.py           ← FastAPI application
│   ├── __init__.py
│   └── requirements.txt   ← Python dependencies
└── package.json

When you run ft-sovx start:

1. CLI locates the bundled backend/ folder
2. Changes working directory to backend/
3. Executes: uvicorn main:app --host 127.0.0.1 --port 8000
4. FastAPI server boots at http://127.0.0.1:8000

🌐 API Endpoints

Health Check (Public)

GET http://127.0.0.1:8000/health

Response: { "status": "healthy", "engine": "Phanorasal Core", "integrity": "nominal" }

Node Start (Authenticated)

POST http://127.0.0.1:8000/api/node/start
Header: X-FT-Sovereign-Key: ft_sovereign_secret_handshake_2026

Node Stop (Authenticated)

POST http://127.0.0.1:8000/api/node/stop
Header: X-FT-Sovereign-Key: ft_sovereign_secret_handshake_2026

⚙️ Environment Variables

# Set deployment mode
export FT_DEPLOYMENT_MODE=local  # or 'cloud'

# Set auth key
export SOVEREIGN_AUTH_KEY=your_secret_key

# Set backend URL
export FT_BACKEND_URL=http://127.0.0.1:8000

🐍 Python Requirements

The bundled requirements.txt includes:

• fastapi (0.111.0) - Web framework
• uvicorn (0.30.1) - ASGI server
• pydantic (2.7.4) - Data validation
• ... and 11 more dependencies

🔒 Security

• All authenticated endpoints require X-FT-Sovereign-Key header
• CORS enabled for cross-origin requests
• Middleware validates all infrastructure commands
• Options requests auto-approved for browser compatibility

📝 Development

To modify the bundled Python backend:

1. Edit npm-distribution/backend/main.py
2. Update npm-distribution/backend/requirements.txt if needed
3. Republish package: npm publish

🎯 Key Feature: Automatic Backend Bootup

Unlike traditional Node/Python setups that require separate processes:

Traditional Approach:
┌─ Terminal 1: npm start    → Node.js CLI
└─ Terminal 2: python app.py → Python backend (manual)

ft-sovx Approach:
┌─ Terminal 1: ft-sovx start → Auto-boots both!

The bundled backend boots automatically in the background when you run ft-sovx start.

📦 Publishing

cd npm-distribution
npm publish

The package will be published with the bundled Python backend included!

🤝 Support

For issues, check:

• ft-sovx status - See if backend is running
• ft-sovx setup - Reinstall Python dependencies
• Backend logs at http://127.0.0.1:8000/health

❓ Troubleshooting

Issue: "Cannot connect to backend server"

Solution: Signup and authentication work without the local backend. This error typically appears during ft-sovx start. Make sure the backend requirements are installed with ft-sovx setup.

Issue: Backend won't start

# Check if Python is installed
python --version

# Reinstall Python dependencies
ft-sovx setup

# Check if port 8000 is already in use
# Either wait for it to free up or use a different port

Issue: "ft-sovx: command not found"

# Reinstall globally
npm install -g ft-sovx

# Or use with npx
npx ft-sovx start

Issue: Credentials lost after logout

This is expected behavior. Use ft-sovx signup or ft-sovx auth to re-authenticate.

Issue: Lost sovereign key

The key is sent to your email during signup. Check your inbox and spam folder.

If you need to retrieve it anytime:

ft-sovx iam --key

This will display your stored sovereign key if you've authenticated previously.

📚 Common Use Cases

Development Setup

# Fresh install
npm install -g ft-sovx

# Register account
ft-sovx signup

# Start development server
ft-sovx start

# View infrastructure status
ft-sovx status

# Check your details
ft-sovx iam

Production Deployment

# Setup with custom environment
export FT_DEPLOYMENT_MODE=cloud

# Start with infrastructure
ft-sovx start

# Monitor health
ft-sovx status

# View system info
ft-sovx configure

CI/CD Integration

# Non-interactive setup
export [email protected]
export FT_PASSWORD=secure_password
ft-sovx auth

# Run tests with backend
ft-sovx start
# ... run your tests ...
ft-sovx stop

Made with ❤️ by Front Terrain