Quick Start Guide

Get your first SocketCloud mesh running in minutes

Table of Contents

Step 1: Installation

SocketCloud is distributed as a private npm package. You'll need valid license credentials to access the package registry.

Enterprise License Required

Access to SocketCloud packages requires an active enterprise license. Packages are hosted on GitHub at github.com/aaimplatform/socket-cloud. Contact contact@socketcloud.com to obtain access.

Once you have your credentials, configure npm to access our GitHub Packages registry:

# Configure npm for GitHub Packages
npm config set @aaimplatform:registry https://npm.pkg.github.com

# Authenticate with your GitHub token
npm config set "//npm.pkg.github.com/:_authToken" "YOUR_GITHUB_TOKEN"

# Or use .npmrc file (recommended for projects)
echo "@aaimplatform:registry=https://npm.pkg.github.com" >> .npmrc
echo "//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}" >> .npmrc

Then install SocketCloud using your preferred package manager:

# Using npm
npm install @aaimplatform/socket-cloud

# Using yarn
yarn add @aaimplatform/socket-cloud

# Using pnpm
pnpm add @aaimplatform/socket-cloud

Step 2: Basic Setup

Create a basic SocketCloud mesh network with state synchronization:

import {
  MeshNetworkImpl,
  StateManagerImpl,
  WebSocketTransport,
  MulticastDiscovery,
  DefaultSecurityProvider,
  generateUUID
} from '@aaimplatform/socket-cloud';

async function main() {
  const nodeId = generateUUID();
  
  // Initialize components
  const security = new DefaultSecurityProvider();
  await security.initialize();
  
  const transport = new WebSocketTransport();
  await transport.initialize();
  
  const discovery = new MulticastDiscovery();
  await discovery.initialize();
  
  const mesh = new MeshNetworkImpl();
  await mesh.initialize();
  
  const state = new StateManagerImpl({ count: 0 });
  
  // Subscribe to state changes
  state.subscribe(newState => {
    console.log('State updated:', newState);
  });
  
  // Start discovery service
  await discovery.start();
  
  // Register with discovery service
  await discovery.register({
    id: nodeId,
    name: `Node-${nodeId.substring(0, 6)}`
  });
  
  // Handle discovered nodes
  discovery.onNodeDiscovered(node => {
    console.log(`Discovered node: ${node.name} (${node.id})`);
    mesh.addNode(node);
  });
  
  // Update state and sync with other nodes
  state.updateState({ count: state.getState().count + 1 });
  await state.sync();
}

main();

Step 3: Register Your First Service

Register a financial service with the distributed mesh:

// Define service identity
const serviceIdentity = {
  id: 'trading-service-001',
  publicKey: 'your-service-public-key',
  capabilities: ['market-data', 'trade-execution', 'risk-calculation'],
  attestation: {
    signature: 'quantum-resistant-signature',
    issuer: 'trusted-authority',
    issuedAt: Date.now(),
    expiresAt: Date.now() + (24 * 60 * 60 * 1000), // 24 hours
    status: 'active',
    claims: {
      purpose: 'financial-trading',
      environment: 'production'
    }
  },
  
  // Mesh-specific properties
  nodeId: 'node-1',
  meshRole: 'participant',
  trustedPeers: ['node-2', 'node-3'],
  distributedCapabilities: [],
  consensusWeight: 1,
  minimumConsensus: 3
};

// Register with consensus
const result = await gateway.registerService(serviceIdentity, true);

if (result.success) {
  console.log('Service registered successfully!');
  if (result.consensusId) {
    console.log('Consensus ID:', result.consensusId);
  }
} else {
  console.error('Service registration failed');
}

Step 4: Authorization Example

Authorize operations for your registered service:

// First, establish a session
const sessionResult = await gateway.establishSession(
  serviceIdentity,
  ['node-1', 'node-2', 'node-3'], // Participant nodes
  3600000 // 1 hour timeout
);

if (sessionResult.success) {
  console.log('Session established:', sessionResult.sessionId);
  
  // Now authorize an operation
  const authRequest = {
    sessionId: sessionResult.sessionId,
    serviceId: 'trading-service-001',
    capability: 'trade-execution',
    resources: ['market-data', 'portfolio-state'],
    context: {
      purpose: 'Execute portfolio rebalancing trade',
      urgency: 'normal',
      requestId: 'req-123'
    },
    requestingNode: 'node-1',
    consensusRequired: false,
    crossNode: false
  };

  const authResponse = await gateway.authorizeOperation(authRequest);
  
  if (authResponse.authorized) {
    console.log('Operation authorized!');
    console.log('Session token:', authResponse.sessionToken);
    console.log('Expires in:', authResponse.expiresIn, 'ms');
  } else {
    console.log('Authorization denied');
    console.log('Restrictions:', authResponse.restrictions);
  }
}

Configuration Options

SocketCloud supports different deployment scenarios:

import { getRecommendedConfig } from '@aerframe/socket-cloud/agent-security';

// Development environment
const devConfig = getRecommendedConfig(
  'development', 
  'dev-node-1', 
  'dev-network', 
  consensusAlgorithm
);

// Production environment
const prodConfig = getRecommendedConfig(
  'production', 
  'prod-node-1', 
  'financial-mesh', 
  consensusAlgorithm
);

// High-security environment
const secureConfig = getRecommendedConfig(
  'high-security', 
  'secure-node-1', 
  'regulated-network', 
  consensusAlgorithm
);

const gateway = new MCPSecurityGateway(prodConfig);

Monitoring and Health Checks

Monitor your SocketCloud deployment:

// Get security status
const status = await gateway.getSecurityStatus();
console.log('Overall status:', status.overall);
console.log('Component health:', status.components);

// Get performance metrics
const metrics = gateway.getSecurityMetrics();
console.log('Recent metrics:', metrics);

// Listen for events
gateway.on('agentRegistered', (event) => {
  console.log(`Agent ${event.agentId} registered`);
});

gateway.on('sessionEstablished', (event) => {
  console.log(`Session ${event.sessionId} established`);
});

gateway.on('authorizationApproved', (event) => {
  console.log(`Authorization approved: ${event.capability}`);
});