nexuscorecloud/space-agent repository overview

⁠SPACE Agent 🚀

Secure Platform for Access, Control & Execution

⁠📋 Overview

SPACE Agent is a lightweight, secure device agent that enables remote access, container deployment, and resource management on edge devices. It connects devices to the NexusCore SPACE platform via secure WebSocket and VPN connections.

⁠✨ Features

• 🔐 Secure Connectivity - WireGuard VPN + WebSocket mesh networking
• 🐋 Container Management - Deploy and manage isolated Docker containers (CAVEs)
• 📊 Hardware Detection - Automatic CPU, RAM, GPU, storage detection
• 🔄 Auto-Provisioning - Zero-touch deployment with one-time tokens
• 📡 Real-time Monitoring - Live hardware stats and container metrics
• 🛡️ Resource Isolation - Per-container CPU, memory, and storage limits
• 🌐 Multi-Brand Support - Isolated environments for different customers

⁠🚀 Quick Start

⁠One-Command Installation

curl -fsSL "https://support.nexuscore.cloud/install-script/{DEVICE_ID}?token={TOKEN}" | bash

⁠Manual Installation

docker run -d \
  --name space-agent \
  --privileged \
  --network host \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /etc/space-agent:/etc/space-agent \
  -v /var/lib/space-agent:/var/lib/space-agent \
  -e DEVICE_ID="your-device-id" \
  -e DEVICE_API_KEY="your-api-key" \
  -e BRAND_ID="your-brand" \
  -e GATEWAY_URL="wss://support.nexuscore.cloud:22090" \
  -e API_URL="https://api.support.nexuscore.cloud/api/v1" \
  nexuscorecloud/space-agent:latest

⁠📦 Environment Variables

⁠🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    SPACE Agent                          │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   Hardware   │  │   Docker     │  │   Resource   │ │
│  │   Detector   │  │  Controller  │  │   Manager    │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│                                                         │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │  WireGuard   │  │  WebSocket   │  │     API      │ │
│  │     VPN      │  │   Gateway    │  │   Reporter   │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
│                                                         │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
              ┌───────────────────────┐
              │  NexusCore Platform   │
              │  - 2B Gateway         │
              │  - ASTEROID Proxy     │
              │  - SPACE URLs         │
              └───────────────────────┘

⁠🔧 System Requirements

• OS: Linux (Ubuntu 20.04+, Debian 11+, Alpine, etc.)
• Architecture: x86_64 (amd64)
• Docker: 20.10+
• Memory: 512MB minimum, 1GB+ recommended
• Storage: 2GB minimum for agent + containers
• Network: Outbound HTTPS (443) and WSS (22090)

⁠🛡️ Security

• ✅ Zero Trust - All connections authenticated with API keys
• ✅ Encrypted - WireGuard VPN + TLS 1.3 for all traffic
• ✅ Isolated - Each customer gets isolated Docker network
• ✅ Resource Limited - CPU, memory, storage quotas enforced
• ✅ One-Time Tokens - Installation tokens expire after use
• ✅ No Hardcoded Secrets - All credentials via environment variables

⁠📊 What Gets Reported

The agent automatically detects and reports:

• CPU: Cores, model, frequency
• Memory: Total, used, free
• Storage: Total, used, free
• GPU: Availability, model, VRAM (if present)
• System: Hostname, OS, architecture, kernel version
• Network: VPN IP, gateway connection status
• Containers: Running CAVEs, resource usage

⁠🔄 Auto-Provisioning Flow

1. Generate Token - Platform creates one-time installation token
2. Download Script - User runs curl command on device
3. Install Docker - Script checks/installs Docker if needed
4. Pull Agent - Downloads latest SPACE Agent image
5. Configure - Creates config with device credentials
6. Start VPN - Downloads and activates WireGuard config
7. Connect - Establishes WebSocket connection to gateway
8. Report - Sends hardware specs to platform
9. Ready - Device online and ready for container deployment

⁠📝 Logs

View agent logs:

docker logs -f space-agent

Check VPN status:

docker exec space-agent wg show

View configuration:

docker exec space-agent cat /etc/space-agent/config.json

⁠🐛 Troubleshooting

⁠Agent won't start

# Check logs
docker logs space-agent

# Verify environment variables
docker inspect space-agent | grep -A 20 Env

⁠VPN not connecting

# Check WireGuard status
docker exec space-agent wg show

# Verify config exists
docker exec space-agent ls -la /etc/wireguard/

⁠Can't deploy containers

# Check Docker socket access
docker exec space-agent docker ps

# Verify resource availability
docker exec space-agent df -h
docker exec space-agent free -h

⁠🔗 Links

• Platform: https://nexuscore.cloud⁠
• Documentation: https://docs.nexuscore.cloud/space-agent⁠
• Support: https://support.nexuscore.cloud⁠
• GitHub: https://github.com/Nexus-Core-Cloud⁠

⁠📄 License

Free agent software. Platform access requires subscription (see pricing⁠).

© 2025 NexusCore Cloud. All rights reserved.

⁠🤝 Support

For issues, questions, or feature requests:

• 📧 Email: [email protected]⁠
• 💬 Support Portal: https://support.nexuscore.cloud⁠
• 📚 Documentation: https://docs.nexuscore.cloud⁠

Engineered by Kai Gartner⁠ | Built with ❤️ by the Nexus Core Team