Configuration Reference

This guide provides a comprehensive reference for configuring VibeX applications. VibeX uses a combination of environment variables, TypeScript configuration, and optional YAML files for agent definitions.

Environment Variables

LLM Provider Keys

VibeX automatically detects the LLM provider based on which environment variable is set:


# OpenAI (recommended)
OPENAI_API_KEY=sk-your-key
 
# Anthropic
ANTHROPIC_API_KEY=your-key
 
# DeepSeek (cost-effective)
DEEPSEEK_API_KEY=your-key
 
# Google Gemini
GOOGLE_GENERATIVE_AI_API_KEY=your-key

Storage Configuration


# Supabase (for cloud storage)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-key
 
# Local storage path (optional, defaults to ./data)
VIBEX_DATA_PATH=./data

Application Settings


# Environment
NODE_ENV=development  # or 'production'
 
# Logging
LOG_LEVEL=info  # debug, info, warn, error

TypeScript Configuration

XAgent.start() Options


import { XAgent } from "vibex";
import { createSupabaseAdapter } from "@vibex/supabase";
 
const xAgent = await XAgent.start(goal, options);

Option	Type	Default	Description
`adapter`	`DataAdapter`	`LocalAdapter`	Storage adapter
`systemPrompt`	`string`	Default XAgent prompt	Custom system prompt

XAgent.resume() Options


const xAgent = await XAgent.resume(spaceId, options);

Option	Type	Default	Description
`adapter`	`DataAdapter`	`LocalAdapter`	Storage adapter (must match original)

streamText() Options


const stream = await xAgent.streamText({
  messages: Message[],
  metadata: Metadata,
});

Field	Type	Required	Description
`messages`	`Message[]`	Yes	Array of conversation messages
`metadata`	`Metadata`	Yes	Request metadata

Message Structure


interface Message {
  role: "user" | "assistant" | "system";
  content: string;
}

Metadata Structure


interface Metadata {
  mode: "agent" | "tool";
  requestedAgent: "X" | string;  // Usually "X" for XAgent
}

Storage Adapters

Local Adapter

Uses SQLite for structured data and filesystem for files.


import { createLocalAdapter } from "@vibex/local";
 
const adapter = createLocalAdapter({
  path: "./data",  // Base path for storage
});

Option	Type	Default	Description
`path`	`string`	`"./data"`	Directory for data storage

Supabase Adapter

Uses PostgreSQL and Supabase Storage for cloud deployment.


import { createSupabaseAdapter } from "@vibex/supabase";
 
const adapter = createSupabaseAdapter({
  supabaseUrl: process.env.SUPABASE_URL!,
  supabaseKey: process.env.SUPABASE_SERVICE_KEY!,
});

Option	Type	Required	Description
`supabaseUrl`	`string`	Yes	Supabase project URL
`supabaseKey`	`string`	Yes	Supabase service key

Agent Configuration

VibeX uses YAML files from @vibex/defaults for agent configuration. These define the specialist agents that XAgent coordinates.

Default Agents

Agent	Role	Description
`X`	Orchestrator	Project manager, coordinates other agents
`researcher`	Research	Gathers and synthesizes information
`writer`	Content	Creates documents and content
`developer`	Code	Writes and reviews code
`reviewer`	QA	Quality assurance and review
`web_designer`	Design	Creates HTML/CSS experiences

Agent YAML Schema

Agent definitions in @vibex/defaults/agents/:


# Example: researcher.yaml
name: researcher
description: "Evidence-based research specialist"
role: researcher
 
# Prompt template reference
prompt_template: prompts/researcher.md
 
# Available tools
tools:
  - web_search
  - memory
  - file_read
 
# LLM configuration
llm_config:
  temperature: 0.3  # Lower for factual research
  max_tokens: 4000

Prompt Templates

Prompts are Markdown files in @vibex/defaults/prompts/:


# Researcher Agent
 
You are an expert researcher skilled in gathering, evaluating, 
and organizing information from multiple sources.
 
## Your Role
- Conduct thorough information gathering
- Evaluate source credibility and relevance
- Organize findings systematically
 
## Guidelines
- Always verify information from multiple sources
- Document sources and methodology
- Identify potential biases or limitations

Space Configuration

Space Properties

Property	Type	Description
`spaceId`	`string`	Unique identifier (auto-generated)
`name`	`string`	Human-readable name
`goal`	`string`	Workspace objective
`history`	`History`	Conversation history
`createdAt`	`Date`	Creation timestamp
`updatedAt`	`Date`	Last update timestamp

Space Methods


const space = xAgent.getSpace();
 
// Save workspace state
await space.persistState();
 
// Access properties
console.log(space.spaceId);
console.log(space.name);
console.log(space.goal);
console.log(space.history.messages.length);

React Integration

Provider Setup


// app/providers.tsx
import { VibexProvider } from "@vibex/react";
 
export function Providers({ children }) {
  return (
    <VibexProvider>
      {children}
    </VibexProvider>
  );
}

Available Hooks

Hook	Purpose
`useSpace(spaceId)`	Access Space state and metadata
`useChat(spaceId)`	Chat interface with message history
`useArtifact(spaceId, artifactId)`	Access artifact content

useSpace Hook


const { space, isLoading, error } = useSpace(spaceId);

useChat Hook


const {
  messages,
  sendMessage,
  isLoading,
  error,
} = useChat(spaceId);
 
// Send a message
await sendMessage("Write an introduction");

Production Checklist

Security

API keys stored in environment variables (not code)
.env file in .gitignore
Service keys have appropriate permissions
Rate limiting configured

Performance

Appropriate LLM model selected for task
Streaming enabled for better UX
Storage adapter optimized for use case

Reliability

Error handling implemented
State persistence before exit
Graceful shutdown handlers

Monitoring

Logging configured appropriately
Error tracking in place
Usage metrics collected

Example Configurations

Development Setup


# .env.development
OPENAI_API_KEY=sk-dev-key
NODE_ENV=development
LOG_LEVEL=debug
VIBEX_DATA_PATH=./data

Production Setup


# .env.production
OPENAI_API_KEY=sk-prod-key
SUPABASE_URL=https://prod.supabase.co
SUPABASE_SERVICE_KEY=prod-service-key
NODE_ENV=production
LOG_LEVEL=info

Next.js App Router


// app/api/chat/route.ts
import { XAgent } from "vibex";
 
export async function POST(req: Request) {
  const { spaceId, message } = await req.json();
  
  const xAgent = await XAgent.resume(spaceId);
  const stream = await xAgent.streamText({
    messages: [{ role: "user", content: message }],
    metadata: { mode: "agent", requestedAgent: "X" },
  });
  
  return new Response(stream.toReadableStream());
}

Troubleshooting

Common Issues

“API key not found”

Ensure the correct environment variable is set
Check that dotenv/config is imported before using the key
Verify the key is valid and has credits

“Space not found”

Verify the spaceId is correct
Ensure the same storage adapter is used for resume
Check that the data wasn’t deleted

“Network error”

Check internet connectivity
Verify API endpoint is accessible
Check for rate limiting

Debug Mode

Enable debug logging:


LOG_LEVEL=debug

Or programmatically:


process.env.LOG_LEVEL = "debug";