Setup Handbook

This guide provides a comprehensive walkthrough on configuring Cyne AI for various use cases and environments.

Environment Configuration

Basic Setup

Start by creating an environment configuration file:

cp .env.example .env

---

Core Environment Variables

These are the essential environment variables required to configure Cyne AI:

# Core API Keys
OPENAI_API_KEY=sk-your-openai-key       # For AI functionality
CYNE_SERVER_URL=                        # Optional custom AI endpoint

# Solana Configuration
SOLANA_NETWORK=mainnet-beta             # Solana network (e.g., devnet, mainnet-beta)
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com  # Solana RPC endpoint

---

Character Configuration

Character File Structure

Character files define the personality, behavior, and capabilities of Cyne AI agents. These files are stored in the characters/ directory.

Example structure:

{
    "name": "AgentName",
    "clients": ["telegram", "discord"],
    "modelProvider": "openai",
    "settings": {
        "secrets": {
            "OPENAI_API_KEY": "character-specific-key"
        }
    }
}

---

Loading Characters

You can load character files during runtime:

# Load the default character
pnpm start

# Load a specific character
pnpm start --characters="characters/agent-name.json"

# Load multiple characters
pnpm start --characters="characters/agent1.json,characters/agent2.json"

---

Action Configuration

Adding Custom Actions

To extend the agent's functionality, add custom actions:

1. Create a custom_actions/ directory.

2. Add your action files (e.g., myCustomAction.ts) to this directory.

Example custom action configuration:

export const myCustomAction: Action = {
    name: "CUSTOM_ACTION",
    similes: ["ACTION_TRIGGER", "ALTERNATIVE_TRIGGER"],
    validate: async (runtime: IAgentRuntime, message: Memory) => {
        // Custom validation logic
        return true;
    },
    description: "Description of the action's purpose.",
    handler: async (runtime: IAgentRuntime, message: Memory) => {
        // Action implementation logic
    },
};

---

Provider Configuration

Solana Provider

To configure the Solana provider, update the environment variables:

SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
SOLANA_NETWORK=mainnet-beta

You can register the Solana provider during runtime:

runtime.registerContextProvider(solanaProvider);

---

Market Data Provider

This provider retrieves real-time token prices and trading volumes.

Example:

const marketDataProvider: Provider = {
    get: async (runtime: IAgentRuntime, message: Memory) => {
        const token = message.content.text; // Extract token name
        const marketData = await runtime.getMarketData(token); // Fetch market data
        return `The current price of ${token} is ${marketData.price} SOL.`;
    },
};

---

Advanced Configuration

Runtime Settings

Customize runtime behavior with the following settings:

const settings = {
    // Logging
    DEBUG: "cyne:*",
    LOG_LEVEL: "info",

    // Performance
    MAX_CONCURRENT_REQUESTS: 5,
    REQUEST_TIMEOUT: 30000,

    // Memory
    MEMORY_TTL: 3600,           // Time-to-live for memory entries (seconds)
    MAX_MEMORY_ITEMS: 1000,     // Maximum number of memory entries
};

---

Plugin Management

Enable and configure plugins by defining them in the configuration file:

plugins:
    - name: solana
      enabled: true
      settings:
          network: mainnet-beta
          endpoint: https://api.mainnet-beta.solana.com

---

Configuration Best Practices

Environment Segregation

• Use separate .env files for development, staging, and production.

• Follow naming conventions: .env.development, .env.staging, .env.production.

---

Secret Management

• Never commit sensitive keys or secrets to version control.

• Use secret management tools for production environments.

• Rotate API keys regularly.

---

Character Configuration

• Keep character files modular for easy customization.

• Use inheritance or shared configuration files for common traits.

---

Plugin Management

• Enable only the necessary plugins to reduce resource usage.

• Use separate configuration files for each plugin to isolate settings.

---

Database Configuration

• Use SQLite for development environments.

• Configure connection pooling for production databases (e.g., PostgreSQL).

• Optimize database performance with appropriate indexes.

---

Troubleshooting

Common Issues

1. Environment Variables Not Loading Verify the location and syntax of the .env file:

   node -e "console.log(require('path').resolve('.env'))"

2. Character Loading Failures Validate the structure of the character file:

   npx ajv validate -s character-schema.json -d characters/agent-name.json

3. Database Connection Issues Test the database connection with the following script:

   npx ts-node scripts/test-db-connection.ts

---

Configuration Validation

Use the built-in configuration validator:

pnpm run validate-config

This will validate:

• Environment variables

• Character files

• Database configuration

• Plugin settings

---

Further Resources

• Quickstart Guide: Learn how to set up your first Cyne AI agent.

• Secrets Management: Securely manage API keys and sensitive information.

• Plugin Development: Build custom plugins to extend Cyne AI.

• Local Development: Optimize your local environment for Cyne AI development.

---

By following this guide, you can configure Cyne AI to operate effectively in any environment, ensuring seamless interactions with the Solana blockchain ecosystem.