# 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

```json
{
  "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

```json
{
  "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

```json
{
  "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:

```bash
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:

```bash
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**.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pil.so/configuration-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.