Getting Started

This guide gets a local Delibera cluster running on your machine. You will have a coordinator, one or more workers, and the frontend dashboard.

Prerequisites

• Node.js 20+ (LTS recommended)
• Rust (stable + nightly) — for building NEAR smart contracts
• NEAR testnet account — create one at wallet.testnet.near.org

Clone and Configure

git clone https://github.com/your-org/near-shade-coordination.git
cd near-shade-coordination

Copy the example environment files for both the coordinator and worker agent:

cp coordinator/.env.example coordinator/.env
cp worker-agent/.env.example worker-agent/.env

Edit each .env file with your credentials:

# Required for both coordinator and worker
NEAR_ACCOUNT_ID=yourname.testnet
NEAR_SEED_PHRASE="your twelve word seed phrase here"

# Ensue shared state
ENSUE_API_KEY=your-ensue-api-key

# NEAR AI reasoning
NEAR_AI_API_KEY=your-near-ai-api-key

Run the Cluster

A single script starts everything:

./run-dev.sh

This launches:

| Service | Port | Description | |---|---|---| | Coordinator | 3000 | Dispatches proposals, aggregates votes | | Worker 1 | 3001 | First AI deliberation agent | | Frontend | 3004 | Next.js dashboard |

To run multiple workers:

WORKER_COUNT=3 ./run-dev.sh

Workers will bind to ports 3001, 3002, and 3003.

Local Mode

By default, LOCAL_MODE=true is set in development. This skips TEE attestation and on-chain contract calls, letting you iterate without a NEAR account or Phala deployment.

Verify It Works

Check that a worker is healthy:

curl http://localhost:3001/

You should get a JSON response indicating the worker is running. Open http://localhost:3004 in your browser to access the dashboard.

Next Steps

• Read How It Works to understand the full deliberation flow.
• See the Architecture section for a deeper dive into coordinator, workers, and contracts.
• Deploy a worker to Phala TEE using the Deployment Guide.