Configuration (Local vs. UI)

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• .env.example
• apps/web/src/lib/secret-management/secretResolver.ts
• apps/examples/mcp-config.example.json
• packages/core/README.md
• packages/mcp-server/README.md
• packages/core/src/utils/persistence/README.md

The lucky project employs a dual environment system for configuration, separating the context for local development (SDK/CLI) from UI-based workflows (often considered production). This separation allows developers to work with local files and environment variables for rapid iteration, while the UI environment uses a more secure and persistent storage mechanism for secrets and configurations.

This document outlines the architecture, components, and data flow for both configuration contexts, highlighting their differences and the current state of integration between them.

Sources: README.md:82-89

Configuration Contexts

The system's configuration strategy is split into two primary execution contexts.

1. Local Development (SDK/CLI)

This context is designed for local development and testing. It relies on local files for configuration, providing direct access without requiring authentication or a database connection.

• Environment Variables: Loaded from .env and .env.local files at the repository root.
• MCP Servers: Configured in a local JSON file, typically mcp-secret.json. The path to this file is specified by the MCP_SECRET_PATH environment variable.
• Persistence: Can use in-memory storage for workflows by setting USE_MOCK_PERSISTENCE=true, bypassing the need for a Supabase database. Workflow configurations can also be persisted to local JSON files.

Sources: README.md:84-89, README.md:188-191, packages/core/src/utils/persistence/README.md:203-206

2. UI-Based Workflows (Production)

This context is used when running workflows from the web interface. It is designed to be more secure and user-friendly, storing sensitive information in a database.

• API Keys: Stored encrypted in a Supabase database table named lockbox.user_secrets. These are managed via the Settings → Providers page in the UI.
• MCP Servers: Configured via the Settings → Connectors page in the UI and stored in the browser's localStorage.
• Secret Resolution: Secrets like API keys are accessed during workflow invocation via the secretResolver.

Sources: README.md:91-96, apps/web/src/lib/secret-management/secretResolver.ts

Comparison Summary

Feature	Local Development (SDK/CLI)	UI-Based Workflows (Production)
API Keys	Plain text in .env / .env.local files.	Encrypted in Supabase lockbox.user_secrets.
MCP Servers	Defined in mcp-secret.json file. Path set by MCP_SECRET_PATH env var.	Stored in browser localStorage via UI. Not yet connected to execution.
Persistence	In-memory (USE_MOCK_PERSISTENCE=true) or local JSON files.	Supabase database.
Authentication	Not required.	Clerk authentication is integrated.

Sources: README.md:82-96, README.md:188-191

Local Configuration Flow

In the local development context, configuration is sourced from environment variables and local JSON files. This allows for quick setup and iteration without a database.

The diagram below shows how local configuration is loaded for workflow execution.

Environment Variables

The .env.example file lists the environment variables used for local configuration. You can copy this to .env.local to set your own values.

Variable	Description
OPENROUTER_API_KEY	API key for OpenRouter.
OPENAI_API_KEY	API key for OpenAI.
ANTHROPIC_API_KEY	API key for Anthropic.
LUCKY_API_KEY	API key for the Lucky service.
MCP_SECRET_PATH	Path to the JSON file containing MCP server configurations.
USE_MOCK_PERSISTENCE	If true, uses in-memory storage instead of Supabase.
DATABASE_URL	Connection string for the Supabase database.
NEXT_PUBLIC_SUPABASE_URL	Public URL for the Supabase project.
NEXT_PUBLIC_SUPABASE_ANON_KEY	Public anonymous key for the Supabase project.
SUPABASE_SERVICE_ROLE_KEY	Service role key for Supabase admin operations.

Sources: .env.example

MCP Server Configuration

For local development, Model Context Protocol (MCP) servers are defined in a JSON file. The README.md and mcp-server/README.md provide examples of this configuration.

An example mcp-config.example.json file shows the structure:

{
  "tavily": {
    "command": "tavily-mcp",
    "env": {
      "TAVILY_API_KEY": "YOUR_TAVILY_API_KEY"
    }
  },
  "firecrawl": {
    "command": "firecrawl-mcp",
    "env": {
      "FIRECRAWL_API_KEY": "YOUR_FIRECRAWL_API_KEY"
    }
  }
}

Sources: apps/examples/mcp-config.example.json, README.md:100-103

This file maps a tool name (e.g., tavily) to its command and required environment variables. The core execution engine uses this file to set up and run MCP tools during a workflow.

Sources: README.md:138-142, packages/mcp-server/README.md:33-43

UI Configuration Flow

In the UI-based context, configurations are managed through the web interface and stored in a combination of a Supabase database and browser localStorage.

The diagram below illustrates the UI configuration flow and highlights the current gap in MCP server integration.

API Key Management

API keys are managed in the UI and stored securely.

1. Storage: Keys are entered in the Settings → Providers page.
2. Persistence: They are encrypted and saved in the lockbox.user_secrets table in Supabase.
3. Resolution: During workflow execution, the secretResolver is responsible for retrieving and decrypting these keys for use by the models. The implementation details of secretResolver.ts are not specified, but its role is defined.

Sources: README.md:91-96, apps/web/src/lib/secret-management/secretResolver.ts

MCP Configuration Gap

There is a documented gap between how MCP servers are configured in the UI and how they are used by the execution engine.

• UI Configuration: MCP server settings are configured in Settings → Connectors and stored in the browser's localStorage under the key "mcp_servers_config".
• Execution Usage: The core execution engine (packages/core) reads MCP configuration from a local mcp-secret.json file, as it does in the local development context.

Currently, the MCP configurations from the UI's localStorage are not passed to the core execution engine. To bridge this gap, the MCP configurations would need to be persisted to the database (similar to API keys) and then dynamically loaded by the execution engine.

Sources: README.md:144-156

File-Based Workflow Persistence

In addition to environment configuration, the system supports persisting entire workflow definitions to local JSON files. This is primarily a feature of the local development environment.

The persistWorkflow function handles saving a WorkflowConfig object to a specified file.

• Atomic Writes: The function performs atomic writes by first creating a timestamped backup of the existing file before overwriting it. This prevents data loss if the write operation fails.
• Backup Management: It creates backups in a dedicated directory, typically packages/core/logs/backups.
• Default Location: If no filename is provided, it defaults to setupfile.json in the configured output directory.

This mechanism allows developers to save, version, and share workflow structures as simple JSON files.

Sources: packages/core/src/utils/persistence/README.md:203-233, packages/core/src/workflow/setup/tests/resultPersistence.test.ts:10-15, 125-139

Summary

The project's configuration is thoughtfully divided into two distinct contexts to serve both developers and UI users. The local SDK/CLI environment is optimized for speed and ease of use, relying on .env files and local JSON for configuration. The UI-based environment prioritizes security and user management by storing secrets in a database.

A key area for future development is bridging the gap in MCP server configuration, which would allow workflows designed in the UI to seamlessly use the MCP tools configured there. Currently, MCP tools can only be configured for execution via a local mcp-secret.json file, regardless of whether the workflow is initiated from the UI or the CLI.

Sources: README.md:82-96, 144-156