# Running Locally

Guide for running NCN Network services on your local machine for development.

***

## Quick Start

```bash
# Terminal 1: Start P2P Registry
cargo run --bin p2p_registry_node

# Terminal 2: Start Gateway
cargo run --bin gateway_node

# Terminal 3: Start Compute Node
cargo run --bin compute_node -- --gateway-addr http://127.0.0.1:50051

# Terminal 4: Run Test Client
cargo run --bin test_client
```

***

## Prerequisites

* [Environment Setup](/nc/neurochainai-guides/development/environment-setup.md) completed
* [Project Built](/nc/neurochainai-guides/development/building.md) successfully
* 4 terminal windows available

***

## Step 1: Start P2P Registry

The P2P Registry must start first as other services depend on it.

```bash
# Start with default settings
cargo run --bin p2p_registry_node

# Or with custom settings
cargo run --bin p2p_registry_node -- \
  --grpc-listen-addr 127.0.0.1:50050 \
  --p2p-listen-addr /ip4/0.0.0.0/tcp/8828
```

### Expected Output

```
Starting P2P Registry Node...
P2P listening on /ip4/0.0.0.0/tcp/8828
Local peer ID: 12D3KooW...
gRPC server listening on 127.0.0.1:50050
✓ Validator pool initialized
✓ Mempool initialized
✓ P2P Registry ready
```

### Verify Registry

```bash
# Check gRPC is responding
grpcurl -plaintext localhost:50050 list
```

***

## Step 2: Start Gateway Node

Open a new terminal:

```bash
# Navigate to project root
cd ncn-network-v2-rs

# Copy example environment file
cp gateway_node/env.example gateway_node/.env

# Edit configuration if needed
nano gateway_node/.env

# Start Gateway
cargo run --bin gateway_node
```

### Environment Variables

Create or edit `gateway_node/.env`:

```bash
# Required
REGISTRY_GRPC_ADDR=http://127.0.0.1:50050

# Optional (defaults shown)
GRPC_ADDR=127.0.0.1:50051
HTTP_ADDR=127.0.0.1:8080
WS_ADDR=127.0.0.1:9000

# Development mode
REQUIRE_PAYMENT=false
ENABLE_PAYMENT_VERIFICATION=false

# Logging
RUST_LOG=info
```

### Expected Output

```
Starting Gateway Node...
Connecting to Registry at http://127.0.0.1:50050
✓ Connected to Registry
gRPC server listening on 127.0.0.1:50051
HTTP server listening on 127.0.0.1:8080
WebSocket server listening on 127.0.0.1:9000
✓ Gateway ready
```

### Verify Gateway

```bash
# Check HTTP health
curl http://localhost:8080/health

# Check gRPC
grpcurl -plaintext localhost:50051 list
```

***

## Step 3: Start Compute Node

Open a new terminal:

```bash
# Navigate to project root
cd ncn-network-v2-rs

# Start Compute Node
cargo run --bin compute_node -- \
  --gateway-addr http://127.0.0.1:50051 \
  --model-path ./models
```

### Configuration Options

```bash
cargo run --bin compute_node -- \
  --gateway-addr http://127.0.0.1:50051 \
  --model-path ./models \
  --sandbox-mode disabled \
  --execution-timeout 300
```

### Environment Variables

```bash
export SANDBOX_MODE=disabled      # For development
export REQUIRE_PAYMENT=false      # Skip payment verification
export RUST_LOG=info
```

### Expected Output

```
Starting Compute Node...
Connecting to Gateway at http://127.0.0.1:50051
✓ Registered with Gateway
Waiting for tasks...
```

### Verify Compute Node

The Gateway logs should show:

```
Compute node registered: compute-xxx (wallet: 0x...)
```

***

## Step 4: Run Test Client

Open a new terminal:

```bash
# Navigate to project root
cd ncn-network-v2-rs

# Run test client
cargo run --bin test_client
```

### Expected Output

```
╔════════════════════════════════════════╗
║  NCN Network Test Client               ║
╚════════════════════════════════════════╝

Connecting to Gateway at http://127.0.0.1:50051...
✓ Connected to Gateway

📤 Submitting inference request...
Task ID: req-abc123
Status: queued

⏳ Waiting for result...
✓ Received result

Output: [model output data]

✅ Test completed successfully!
```

***

## Local Development Workflow

### Full Stack Command Reference

```bash
# Terminal 1 - Registry
cargo run --bin p2p_registry_node

# Terminal 2 - Gateway
REQUIRE_PAYMENT=false cargo run --bin gateway_node

# Terminal 3 - Compute
SANDBOX_MODE=disabled cargo run --bin compute_node -- \
  --gateway-addr http://127.0.0.1:50051

# Terminal 4 - Test Client
cargo run --bin test_client
```

### Using cargo-watch (Auto-Restart)

```bash
# Install cargo-watch
cargo install cargo-watch

# Auto-restart on file changes
cargo watch -x "run --bin gateway_node"
```

***

## Local Blockchain (Optional)

For testing with payments:

### Start Anvil

```bash
# Start local Ethereum node
anvil

# Expected output:
# Available Accounts (10)
# Private Keys (10)
# Listening on 127.0.0.1:8545
```

### Deploy Contracts

```bash
cd contracts

# Deploy to local Anvil
forge script script/Deploy.s.sol \
  --rpc-url http://127.0.0.1:8545 \
  --broadcast
```

### Configure Gateway for Payments

```bash
# gateway_node/.env
RPC_URL=http://127.0.0.1:8545
CONTRACT_ADDRESS=0x... # From deployment output
REQUIRE_PAYMENT=true
ENABLE_PAYMENT_VERIFICATION=true
GATEWAY_WALLET_PRIVATE_KEY=0x... # Anvil account
```

***

## Port Reference

| Service           | Port  | Protocol  |
| ----------------- | ----- | --------- |
| P2P Registry gRPC | 50050 | gRPC      |
| P2P Registry P2P  | 8828  | libp2p    |
| Gateway gRPC      | 50051 | gRPC      |
| Gateway HTTP      | 8080  | HTTP      |
| Gateway WebSocket | 9000  | WebSocket |
| Anvil (optional)  | 8545  | JSON-RPC  |

***

## Debugging Tips

### Enable Debug Logging

```bash
# All components
export RUST_LOG=debug

# Specific component
export RUST_LOG=gateway_node=debug

# Trace level
export RUST_LOG=trace
```

### Check Service Connectivity

```bash
# Registry health
grpcurl -plaintext localhost:50050 list

# Gateway health
curl http://localhost:8080/health

# Gateway gRPC
grpcurl -plaintext localhost:50051 list
```

### View Active Connections

```bash
# Check listening ports
netstat -tlnp | grep -E "(50050|50051|8080|9000|8828)"

# Or using lsof
lsof -i :50051
```

***

## Common Issues

### "Connection refused" to Registry

```bash
# Ensure Registry is running first
ps aux | grep p2p_registry

# Check port is listening
netstat -tlnp | grep 50050
```

### "No compute nodes available"

* Ensure Compute Node is running
* Check Gateway logs for registration
* Verify model paths exist

### "Sandbox failed" on Compute

```bash
# Disable sandbox for development
export SANDBOX_MODE=disabled
cargo run --bin compute_node -- --gateway-addr http://127.0.0.1:50051
```

### Changes not taking effect

```bash
# Rebuild after changes
cargo build

# Or use cargo-watch
cargo watch -x "run --bin gateway_node"
```

***

## Next Steps

* [Testing](/nc/neurochainai-guides/development/testing.md) - Run the test suite
* [Debugging](/nc/neurochainai-guides/development/debugging.md) - Debug issues
* [Docker Deployment](/nc/neurochainai-guides/deployment/docker.md) - Deploy with Docker


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.neurochain.ai/nc/neurochainai-guides/development/running-locally.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.