Skip to main content
One .praisonai/config.yaml wires your project’s full agent runtime — model, MCP servers, permissions — for every praisonai run in the directory.

​
Quick Start

1

Drop a config file

Create .praisonai/config.yaml in your project root:
# .praisonai/config.yaml
agent:
  model: gpt-4o

mcp:
  servers:
    playwright:
      command: ["npx", "-y", "@playwright/mcp"]

permissions:
  default: ask
  rules:
    - { pattern: "bash:git *", action: allow }
    - { pattern: "bash:rm *",  action: deny }
2

Run anywhere in the project

praisonai run "Open the docs site and screenshot the home page"
Model, MCP server, and permission rules are picked up automatically — no flags needed.
3

Verify resolution

praisonai config show --sources
Shows which layers contributed (defaults, global, project, env, CLI).

​
How It Works

The resolver deep-merges five layers (highest wins):
LayerSourcePrecedence
1Built-in defaultsLowest
2~/.praisonai/config.yaml (global)
3.praisonai/config.yaml (project, walk-up)
4Environment variables
5CLI flagsHighest
CLI flags always win. Config fills the gaps.

​
Configuration Schema

​
mcp.servers.<name>

KeyTypeDefaultDescription
commandlist[str] or str—Local (stdio) server launch command. List form preferred.
argslist[str][]Extra args appended to command.
envdict[str, str]{}Env vars for the server process. Values containing , are skipped on the command-string CLI path.
enabledbooltrueSet false to declare-but-not-wire a server.
type"remote"—Marks a remote server; skipped by the run command-string path.
urlstr—Remote endpoint; presence implies remote.
Only one enabled local (stdio) server is wired through praisonai run. If multiple enabled local servers are declared, a warning is emitted and the first is used. Remote servers (type: remote or a url field) are skipped by the run path but still work for other integrations.

​
permissions

Two equivalent forms: Structured (rule list): 
permissions:
  default: ask
  rules:
    - { pattern: "bash:git *", action: allow }
    - { pattern: "bash:rm *",  action: deny }
Flat mapping: 
permissions:
  "read:*": allow
  "bash:rm *": deny
  "*": ask
KeyTypeDefaultDescription
default"allow" | "deny" | "ask"—Fallback action when no rule matches. Equivalent to "*": <default> in flat form.
ruleslist[{pattern, action}][]Structured rule list. action must be allow, deny, or ask. Invalid actions are silently dropped.
<pattern>"allow" | "deny" | "ask"—Flat shorthand. Can be combined with rules and default.

​
Precedence

  • --mcp, if present, replaces the config MCP server entirely.
  • --allow / --deny / --permissions are merged on top of config rules — CLI wins per-pattern.
  • --permission-default sets the fallback action, overriding permissions.default from config.

​
Common Patterns

​
Pin a model + a single MCP server

# .praisonai/config.yaml
agent:
  model: gpt-4o-mini

mcp:
  servers:
    filesystem:
      command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."]

praisonai run "List all Python files in the project"

​
CI-safe defaults

# .praisonai/config.yaml
agent:
  model: gpt-4o

permissions:
  default: deny
  rules:
    - { pattern: "read:*",    action: allow }
    - { pattern: "bash:git *", action: allow }
All tool calls are denied unless explicitly allowed — safe for unattended CI runs.

​
Mix with CLI flags

Config gives the base; flags override per-run: 
# Override MCP server for this run only
praisonai run "Scrape the homepage" --mcp "npx -y @playwright/mcp"

# Add an extra allow rule on top of config
praisonai run "Deploy" --allow 'bash:kubectl *'

​
Declare-but-not-wire a server

mcp:
  servers:
    experimental:
      command: ["node", "my-mcp-server.js"]
      enabled: false   # declared but not activated

​
Best Practices

Checked-in config ensures every teammate and CI runner uses the same model, MCP servers, and permission defaults automatically.
mcp.servers.<x>.env is fine for non-secret config values (paths, flags). For API tokens, use shell environment variables — they are read by the server process at runtime without being stored in YAML.
When behaviour is unexpected, praisonai config show --sources prints exactly which layer won for each key.
The rules: list is evaluated in order; priority fields are respected. The flat mapping form is convenient for simple deny lists but gives no ordering guarantees.

CLI Configuration

Full cascade reference for the praisonai CLI config layers

Declarative Permissions

All surfaces for pre-declaring allow/deny rules

MCP Transports

Remote MCP server configuration

Config CLI Reference

praisonai config subcommand reference