Skip to content
nXCC

Running a Node

This guide covers running nXCC nodes for different purposes, from local development to production deployments.

Section titled “Local Development (Recommended)”

For developing and testing workers locally, the easiest approach is using the provided run.sh script.

Prerequisites

Section titled “Prerequisites”

Quick Start

Section titled “Quick Start”

From the node/ directory of the nXCC repository:

# Start a single local node
./run.sh


# Start multiple nodes for P2P testing
./run.sh 3

The script automatically:

  • Builds all required binaries (nxcc-daemon, nxcc-platform-enclave, nxcc-workerd-vm)
  • Sets up temporary directories with proper configurations
  • Starts all components with appropriate inter-process connections
  • Exposes HTTP API on ports 6922+ (6922 for first node, 6923 for second, etc.)

Development Workflow

Section titled “Development Workflow”

Once your node is running, you can deploy workers using the CLI:

# Install the CLI
npm install -g @nxcc/cli


# Deploy a worker to your local node
nxcc worker deploy path/to/worker.manifest.json --rpc-url http://localhost:6922

The run.sh script provides full logging output, making it easy to debug your workers and see the system behavior.

Cleanup

Section titled “Cleanup”

Press Ctrl+C to stop all nodes. The script automatically cleans up temporary files and processes.

Production Infrastructure

Section titled “Production Infrastructure”

For production deployments and cloud infrastructure, use the comprehensive infra.sh script from the repository root.

Infrastructure Management Overview

Section titled “Infrastructure Management Overview”

The infra.sh script is a full-featured infrastructure management tool that handles:

  • Local Development: KinD clusters and container builds
  • Cloud Deployment: GCP GKE clusters with TDX support
  • CI/CD Setup: GitHub Actions integration with Workload Identity
  • TDX Development: Special VMs for testing on real TDX hardware

Quick Start with Local Infrastructure

Section titled “Quick Start with Local Infrastructure”
# Complete local setup
./infra/infra.sh image build --debug  # Build debug container images
./infra/infra.sh cluster create kind  # Create local Kubernetes cluster
./infra/infra.sh image push kind      # Load images into cluster
./infra/infra.sh k8s deploy debug     # Deploy nXCC to cluster
./infra/infra.sh test debug           # Test the deployment

Production GCP Deployment

Section titled “Production GCP Deployment”
# One-time CI/CD setup
./infra/infra.sh ci setup


# Production deployment
./infra/infra.sh image build --release # Build optimized container images
./infra/infra.sh image push gcp        # Push to Artifact Registry
./infra/infra.sh cluster create gke    # Create GKE cluster with TDX nodes
./infra/infra.sh k8s deploy prod       # Deploy to production
./infra/infra.sh test prod             # Verify deployment

TDX Hardware Development

Section titled “TDX Hardware Development”

For testing on real Intel TDX hardware:

# Create TDX-enabled development VM
./infra/infra.sh dev create


# SSH into the VM
./infra/infra.sh dev ssh


# Push local code changes
./infra/infra.sh dev push


# Check VM status
./infra/infra.sh dev status


# Clean up when done
./infra/infra.sh dev destroy

The TDX development environment includes:

  • Intel TDX-enabled Google Cloud VM
  • Pre-installed development tools and dependencies
  • nXCC codebase ready for compilation and testing
  • Docker and container tools for building images

Key Features

Section titled “Key Features”
  • Idempotent operations: Safe to run multiple times without side effects
  • Multi-environment support: Local (KinD), staging, and production deployments
  • TDX integration: Proper handling of Intel Trust Domain Extensions for confidential computing
  • Comprehensive testing: Built-in connectivity and functionality tests
  • Developer-friendly: Automated setup and teardown for rapid iteration

For complete details on all commands and options, see the Infrastructure Management Reference.

Manual Setup (Advanced)

Section titled “Manual Setup (Advanced)”

For custom deployments or debugging, you can run components individually:

# Build the workspace
cargo build


# Run components manually (see run.sh for configuration examples)
./target/debug/nxcc-daemon --identity-path identity.key --verbose
./target/debug/nxcc-platform-enclave --identity-path identity.key
./target/debug/nxcc-workerd-vm --vm-id vm1

Refer to node/run.sh and node/tests/utils.sh for detailed configuration examples and inter-component communication setup.