Skip to main content
from praisonaiagents import Agent

agent = Agent(name="config-agent", instructions="Load all settings from a single config file.")
agent.start("Use praison.toml as the single source of truth for all settings.")
One .praisonai/config.yaml wires your project’s full agent runtime — model, MCP servers, permissions — for every praisonai run in the directory. 
praisonai run "Open the docs site and screenshot the home page"
The user keeps settings in .praisonai/config.yaml; every praisonai run in the project loads that single source.

​
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. Required for local servers; ignored for remote.
argslist[str][]Extra args appended to command. Local servers only.
envdict[str, str]{}Env vars for the server process. Local servers only.
enabledbooltrueSet false to declare-but-not-wire a server.
type"remote"—Marks a remote server. Optional — a non-empty url also implies remote.
urlstr—Remote endpoint (HTTP-stream, SSE, or WebSocket). Presence implies remote.
headersdict[str, str]{}HTTP headers for remote servers. Ignored for legacy SSE URLs ending in /sse (a warning is printed).
timeoutint (milliseconds)30000Per-server connect timeout. Converted to seconds before being passed to the SDK MCP(...).
praisonai run wires every enabled server under mcp.servers.* — multiple local (stdio) servers and remote (url: / type: remote) servers are all aggregated and exposed to the agent. Servers with enabled: false are skipped silently. If --mcp "<command>" is also given on the command line, its tools are added on top of the config servers, not in place of them.

​
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, merges with config-declared servers — CLI ad-hoc tools are added alongside every enabled config server.
  • --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