Core

Configuration

How Conductor works, how to configure it, and what happens when your AI calls a tool.

How it runs

When you add Conductor to your AI client's config, the client spawns a conductor mcp start process and talks to it over stdin/stdout (stdio transport). The process loads all enabled plugins, registers their tools, and waits for the AI to call them.

You don't need to start it manually. Your AI client handles the process lifecycle. If you want remote access or a shared team server, use HTTP transport instead.

Start commands

terminal

# Default: stdio transport (used by AI clients)
conductor mcp start

# HTTP transport (for remote/shared access)
conductor mcp start --transport http --port 3000

# Specific plugins only
conductor mcp start --plugins filesystem,shell,git

# Debug logging
conductor mcp start --log-level debug

Config file

The config file lives at ~/.conductor/config.json (or wherever CONDUCTOR_CONFIG_DIR points). Run conductor config setup to generate it interactively.

~/.conductor/config.json

// ~/.conductor/config.json
{
  "server": {
    "transport": "stdio",
    "logLevel": "info"
  },
  "plugins": {
    "shell": {
      "enabled": true,
      "allowedCommands": ["ls", "cat", "git", "npm", "node", "python3"],
      "requireApproval": ["rm", "mv", "chmod", "sudo"]
    },
    "filesystem": {
      "enabled": true,
      "allowedPaths": ["~", "/tmp"],
      "requireApproval": ["delete"]
    },
    "database": {
      "enabled": true,
      "connections": {
        "main": "sqlite:~/.conductor/app.db",
        "postgres": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

What happens on every tool call

In order, every time your AI calls a tool:

Input validation

Tool inputs are validated against the plugin's JSON schema before anything else happens. Invalid inputs are rejected immediately.

Approval gate

If the tool has requiresApproval: true, execution pauses and the user must confirm in the terminal. The AI waits for the response.

Circuit breaker check

If the tool's circuit is OPEN (too many recent failures), the call fails fast with an error. The AI is informed and can try something else.

Handler execution

The plugin's handler runs with the validated input. Failures trigger retry with exponential backoff before updating the circuit breaker.

Audit log write

The call, input hash, result status, and SHA-256 chain link are appended to ~/.conductor/audit.log. Cannot be skipped.

Environment variables

All config can be overridden via environment variables. Useful for CI, Docker, or passing secrets without touching the config file.

Variable	Default	Values
`CONDUCTOR_LOG_LEVEL`	`info`	error \| warn \| info \| debug
`CONDUCTOR_CONFIG_DIR`	`~/.conductor`	Override the config directory
`CONDUCTOR_TRANSPORT`	`stdio`	stdio \| http
`CONDUCTOR_PORT`	`3000`	HTTP port (ignored for stdio)
`CONDUCTOR_PLUGINS`	`(all enabled)`	Comma-separated list to activate
`CONDUCTOR_NO_AUDIT`	`false`	Disable audit logging (not recommended)

Useful CLI commands

conductor doctorCheck system health — Node.js, config, database, plugins

conductor config setupInteractive setup wizard

conductor config pathPrint the config directory path

conductor plugins listList all plugins and their status

conductor plugins enable <name>Enable a plugin

conductor plugins disable <name>Disable a plugin

conductor audit listPrint recent audit log entries

conductor mcp start --log-level debugStart with verbose logging for debugging

Next: Plugin reference