Skip to main content

Cyberwave is in Private Beta.

Request early access to get access to the Cyberwave dashboard.

​
Overview

The Cyberwave Cloud Node turns any computer into a managed compute instance that receives inference, training, and simulation commands from the Cyberwave platform. It connects outbound to the Cyberwave MQTT broker, so there is no need to expose ports, configure public URLs, or punch holes in firewalls.
CommunicationOutbound MQTT — works behind NAT and firewalls
Workload modelEach command runs as an independent OS process that survives node restarts
Configurationcyberwave.yml at the root of your repo, or environment variables
IdentityBackend-assigned UUID and slug, persisted locally for re-registration

​
Installation

pip install cyberwave-cloud-node

​
Quick Start

1

Add a cyberwave.yml to your repo

Create a cyberwave.yml at the root of your project:
cyberwave-cloud-node:
  install_script: ./install.sh
  inference: python ./inference.py --params {body}
  simulate: python ./simulate.py --params {body}
  training: python ./training.py --params {body}
  profile_slug: gpu-a100
  heartbeat_interval: 30
The {body} placeholder is replaced at runtime with the JSON parameters received from MQTT.
2

Set your API key

export CYBERWAVE_API_KEY=your-token-here
3

Start the node

cyberwave-cloud-node start
The Cloud Node will:
  1. Run the install_script and report failures
  2. Register with the backend to get a UUID and slug
  3. Connect to MQTT and start accepting commands
  4. Send periodic heartbeats
  5. Execute workloads as independent OS processes and collect results on completion

​
Authentication

The Cloud Node needs an API key to communicate with Cyberwave. Credentials are resolved in this order:
  1. Environment variable — CYBERWAVE_API_KEY
  2. .env file in the current directory
  3. .env file at ~/.cyberwave/.env (shared config)
  4. Stored credentials from cyberwave-cli login (~/.cyberwave/credentials.json)
# .env
CYBERWAVE_API_KEY=your-token
CYBERWAVE_WORKSPACE_SLUG=my-workspace
If you have already logged in with cyberwave-cli, the Cloud Node uses those credentials automatically.
Generate an API key from your Profile page → API Tokens.

​
Configuration

​
cyberwave.yml

Place this file at the root of your project. All fields except the command templates are optional. 
cyberwave-cloud-node:
  install_script: ./install.sh          # runs once on startup
  inference: python ./inference.py --params {body}
  simulate: python ./simulate.py --params {body}
  training: python ./training.py --params {body}
  profile_slug: gpu-a100                # default: "default"
  heartbeat_interval: 30                # seconds, default: 30
  mqtt_host: mqtt.cyberwave.com         # default: mqtt.cyberwave.com
  mqtt_port: 1883                       # default: 1883

​
Environment Variables

All settings can also be provided via environment variables. They override cyberwave.yml values. Required:
VariableDescription
CYBERWAVE_API_KEYYour Cyberwave API token
API and Workspace:
VariableDefaultDescription
CYBERWAVE_WORKSPACE_SLUG—Workspace slug
CYBERWAVE_INSTANCE_SLUG—Slug hint for automated deployments
CYBERWAVE_BASE_URLhttps://api.cyberwave.comAPI base URL
MQTT:
VariableDefaultDescription
CYBERWAVE_MQTT_HOSTmqtt.cyberwave.comMQTT broker host
CYBERWAVE_MQTT_PORT1883MQTT broker port
CYBERWAVE_MQTT_USERNAME—MQTT username if required
CYBERWAVE_MQTT_PASSWORD—MQTT password if required
CYBERWAVE_ENVIRONMENT—Environment prefix for MQTT topics
Commands (alternative to cyberwave.yml):
VariableDescription
CYBERWAVE_INSTALL_SCRIPTInstall script command
CYBERWAVE_INFERENCE_CMDInference command template
CYBERWAVE_SIMULATE_CMDSimulation command template
CYBERWAVE_TRAINING_CMDTraining command template
CYBERWAVE_PROFILE_SLUGNode profile slug
CYBERWAVE_HEARTBEAT_INTERVALHeartbeat interval in seconds

​
CLI Usage

# Start with defaults (reads cyberwave.yml)
cyberwave-cloud-node start

# With a slug hint (backend may assign a different one)
cyberwave-cloud-node start --slug my-gpu-node

# Custom config file
cyberwave-cloud-node start --config ./path/to/cyberwave.yml

# Override profile
cyberwave-cloud-node start --profile gpu-a100

# Custom MQTT broker
cyberwave-cloud-node start --mqtt-host localhost --mqtt-port 1883

# Verbose logging
cyberwave-cloud-node start -v
The --slug parameter is a hint. The backend owns identity assignment and may use your hint or assign a different slug.

​
Programmatic Usage

from cyberwave_cloud_node import CloudNode, CloudNodeConfig

# From config file (recommended)
node = CloudNode.from_config_file()
node.run()

# With a slug hint
node = CloudNode.from_config_file(slug="my-gpu-node")
node.run()

# From environment variables
node = CloudNode.from_env()
node.run()

# Fully programmatic
config = CloudNodeConfig(
    install_script="./install.sh",
    inference="python inference.py --params {body}",
    training="python train.py --params {body}",
    profile_slug="gpu-a100",
    heartbeat_interval=30,
    mqtt_host="mqtt.cyberwave.com",
    mqtt_port=1883,
)
node = CloudNode(config=config, slug="my-gpu-node")
node.run()

​
Process-Based Workloads

Training and inference jobs run as independent OS processes that survive Cloud Node restarts. This means you can upgrade or restart the Cloud Node without killing a running training job.

​
Lifecycle

  1. Command arrives via MQTT — Cloud Node spawns a detached subprocess (start_new_session=True)
  2. Output streams to log files in ~/.cyberwave/workload_logs/
  3. Monitor loop checks every 5 seconds, collects results when the process finishes, and publishes status back via MQTT
  4. On shutdown (Ctrl+C / SIGTERM) — the node stops accepting new commands and exits immediately; running workloads continue in the background

​
Output Files

~/.cyberwave/workload_logs/
├── training_<request_id>.stdout.log
├── training_<request_id>.stderr.log
├── inference_<request_id>.stdout.log
└── inference_<request_id>.stderr.log
Logs are also streamed to the backend in real-time for live monitoring.

​
Instance Identity

After registration, the backend assigns a UUID and slug. This identity is persisted at ~/.cyberwave/instance_identity.json so the node can re-register with the same identity after a restart.

​
MQTT Topics

Command topics (the node subscribes to these):
TopicDescription
cyberwave/cloud-node/{instance_uuid}/commandCommands addressed by UUID
cyberwave/cloud-node/{slug}/commandCommands addressed by slug
Response topic (the node publishes to):
TopicDescription
cyberwave/cloud-node/{instance_uuid}/responseCommand responses and workload results

​
Commands

​
Sending a Command

{
  "command": "inference",
  "request_id": "unique-request-id",
  "params": {
    "model": "gpt-4",
    "input": "Hello world"
  }
}
CommandDescription
inferenceRun the inference command
simulateRun the simulation command
trainingRun the training command
statusGet node status and active workloads
cancelCancel a running workload by PID or request_id

​
Response Format

{
  "status": "ok",
  "request_id": "unique-request-id",
  "slug": "my-gpu-node",
  "instance_uuid": "abc-123",
  "output": "Command output here"
}
On error, status is "error" and an error field replaces output.

​
Checking Status

Send a status command to see active workloads: 
{
  "slug": "my-gpu-node",
  "instance_uuid": "abc-123",
  "is_busy": true,
  "active_workloads": [
    {
      "pid": 12345,
      "type": "training",
      "request_id": "abc-123",
      "running_for_seconds": 3600
    }
  ]
}

​
Cancelling Workloads

Cancel by PID or by the original workload request_id: 
{
  "command": "cancel",
  "request_id": "unique-request-id",
  "params": { "pid": 12345 }
}
Supported signals:
SignalBehavior
SIGTERM (default)Graceful termination, allows cleanup
SIGINTInterrupt (like Ctrl+C)
SIGKILLImmediate force kill

API Key

Generate your API key

Python SDK

Control twins and robots from Python

Edge Overview

Run Cyberwave on edge devices