Skip to content

Configuration

Jump to bottom
lacausecrypto edited this page Apr 6, 2026 · 3 revisions

Configuration

Environment Variables

Variable Default Description
Server
REST_PORT 4242 HTTP server port
REST_HOST 0.0.0.0 HTTP server bind address
OCC_API_KEY — API key for production auth (required when NODE_ENV=production)
Paths
CHAINS_DIR ../chains Directory containing chain YAML files
PIPELINES_DIR ../pipelines Directory containing pipeline YAML files
WORKSPACE_DIR — Additional allowed directory for /download endpoint and read_file/write_file pre-tools
Execution
CLAUDE_CLI claude Path to Claude CLI binary
CLAUDE_BIN claude Alternative Claude binary path (used by executor)
CLAUDE_TIMEOUT_MS 1800000 Default per-step timeout (30 min)
MAX_CONCURRENT_EXECUTIONS 5 Max simultaneous chain executions (queue worker pool size)
EXECUTION_MAX_AGE_DAYS 7 Auto-purge executions older than N days
Storage (SQLite)
OCC_DB <auto> SQLite database for executions + step checkpoints
OCC_QUEUE_DB <auto> SQLite database for the job queue
OCC_STATE_DB <auto> SQLite database for state_load/state_save pre-tools
OCC_VECTOR_DB <auto> SQLite database for vector_query/vector_index pre-tools
OCC_GRAPH_DB <auto> SQLite database for graph_query pre-tool
OCC_SEMANTIC_CACHE_DB <auto> SQLite database for semantic_cache pre-tool
SCHEDULES_FILE <auto> Schedule persistence file path
Security
OCC_ENCRYPTION_KEY — AES-256-GCM key for encrypting provider API keys (required in production)
NODE_ENV — Set to production to require API key auth and encryption key
ENV_VAR_ALLOWLIST — Comma-separated list of env vars accessible via env_var pre-tool
External MCP
MCP_SERVERS_CONFIG <auto> Path to occ-mcp-servers.json (external MCP server config)
LLM Providers
LLM_PROVIDERS_CONFIG <auto> Path to llm-providers.json (provider configs)
OLLAMA_HOST http://localhost:11434 Ollama server URL
Display
NO_COLOR — Disable ANSI colors in Claude output

<auto> means OCC auto-resolves the path based on the server's file location. Override with an explicit path if needed.

.mcp.json

The MCP configuration file tells Claude Code where to find the OCC server:

{
  "mcpServers": {
    "chain-orchestrator": {
      "command": "node",
      "args": ["/absolute/path/to/OCC/mcp-server/dist/index.js"],
      "env": {
        "CHAINS_DIR": "/absolute/path/to/OCC/chains",
        "PIPELINES_DIR": "/absolute/path/to/OCC/pipelines",
        "REST_PORT": "4242"
      }
    }
  }
}

Important: Paths must be absolute. Relative paths resolve from the Claude Code working directory, which may not be what you expect.

.env File

Copy .env.example to .env for local development:

cp .env.example .env

The server reads environment variables from the shell. If you want to use a .env file, use a tool like dotenv-cli:

npx dotenv-cli -- npm run rest

Running Modes

MCP Server (default)

npm start

Runs as MCP server over stdio. Used by Claude Code / Claude Desktop. Also starts the REST API on the configured port.

REST-only

npm run rest

Runs only the REST API server. No MCP. Useful for programmatic access or when Claude CLI calls are made externally.

Full Stack (Backend + Frontend)

# Terminal 1
cd mcp-server && npm run rest

# Terminal 2
cd frontend-react && npm run dev

Docker

docker compose up -d

Development

npm run dev

Watches for file changes and restarts automatically. Uses node --watch.

Deployment

systemd (Linux)

[Unit]
Description=OCC Chain Orchestrator
After=network.target

[Service]
Type=simple
User=occ
WorkingDirectory=/opt/occ
ExecStart=/usr/bin/node mcp-server/dist/rest.js
Restart=always
Environment=NODE_ENV=production
Environment=OCC_API_KEY=your-secret-key
Environment=OCC_ENCRYPTION_KEY=your-encryption-key
Environment=REST_PORT=4242

[Install]
WantedBy=multi-user.target

Docker Compose

See docker-compose.yml in the project root for the production-ready setup.

PM2

pm2 start mcp-server/dist/rest.js --name occ \
  --env NODE_ENV=production \
  --env OCC_API_KEY=your-secret-key \
  --env REST_PORT=4242

See Also

Clone this wiki locally