Configuration Guide

PILSO OS is powered by two core configuration files:

• pilso.config.json → global system and runtime settings

• pilso-roles.json → defines agent personalities, goals, and tool access

These files control how your agents think, what tools they can use, which LLM they speak through, and how results are logged or approved.

---

File 1: pilso.config.json

This is the core runtime configuration file. It defines which LLM provider to use, which tools are available, logging levels, and trusted behaviors.

---

Example

{
  "provider": "claude",
  "apiKey": "sk-xxxxx",
  "tools": [
    "http://localhost:3020",  // metamask-mcp
    "http://localhost:3030",  // erc20-mcp
    "http://localhost:3040"   // solc-mcp
  ],
  "logLevel": "debug",
  "alwaysAllow": ["metamask.sign", "chainlist.getRPC"],
  "timeoutMs": 30000
}

---

Field Reference

Field	Description
provider	LLM engine to use (claude, gpt4, deepseek, etc)
apiKey	Your LLM provider API key
tools	List of MCP server endpoints
logLevel	debug, info, warn, or silent
alwaysAllow	List of tool calls that bypass confirmation prompts
timeoutMs	Timeout for tool execution (in milliseconds)

---

Best Practices

• Always whitelist only safe, idempotent tools in alwaysAllow

• Store sensitive fields like apiKey in environment variables and reference them via a wrapper script or .env loader

• Run your MCP servers locally or through a secure internal proxy

---

File 2: pilso-roles.json

This file defines your agent roles — named personalities that guide behavior, limit tool access, and enforce guardrails.

---

🔧 Example: Minimal signer role

{
  "signer": {
    "description": "Handles wallet transaction signing only.",
    "tools": ["metamask.sign"],
    "goals": [
      "Interpret prepared transaction payloads",
      "Use metamask-mcp to sign after confirmation"
    ],
    "guardrails": [
      "Never generate new contracts",
      "Never deploy",
      "Always confirm intent before signing"
    ]
  }
}

---

Example: Developer role with compile + sign

{
  "developer": {
    "description": "A role for contract deployment and tooling.",
    "tools": ["solc.compile", "metamask.sign", "chainlist.resolve"],
    "goals": [
      "Compile smart contracts",
      "Prepare and sign deploy transactions",
      "Fetch chain config from chainlist-mcp"
    ],
    "guardrails": [
      "Never transfer tokens",
      "Only deploy approved contracts"
    ]
  }
}

---

Field Reference

Field	Description
description	Human-readable summary of the agent’s role
tools	Tool functions this role can access (toolName.method)
goals	Statements used in prompt initialization to guide LLM behavior
guardrails	Safety limitations injected into system prompts

---

Environment Variables (Optional)

You can store API keys and sensitive settings in an .env file or via shell variables. For example:

export PILSO_API_KEY="sk-xxxxx"
export PILSO_PROVIDER="claude"

Then dynamically inject them at runtime using a wrapper or config loader in your dev stack.

---

Updating Configs

You can edit the config files manually, or use built-in CLI helpers:

npx pilso config edit
npx pilso roles add signer
npx pilso roles list

---

Config Tips

• Use separate roles for distinct tasks instead of overloading one agent

• For production use, disable any tool from alwaysAllow that writes onchain

• You can run multiple .pilso environments in different projects for sandboxing

---

Summary

File	Purpose
pilso.config.json	Global agent + tool runtime settings
pilso-roles.json	Role definitions for different agent personalities
.env	Store sensitive keys outside your config file

Config files are the brain and personality of your PILSO environment — they define how your agent behaves, what it can access, and how much trust you delegate.