Install & Launch

This guide covers how to install and launch PILSO OS locally via the CLI. PILSO is distributed as a Node.js nnects to your configured LLM provider, MCP server modules, and Web3 wallet signer.

Whether you’re running a simple session or building a custom agent workflow, everything starts here.

---

Requirements

Before you begin, make sure you have the following installed:

Tool	Version
Node.js	>=18.x (LTS recommended)
npm	>=9.x
Git	For MCP server clones (if local)
MetaMask	Installed + connected in browser (for signing)

• An OpenAI, Anthropic or DeepSeek API key

• Local or remote MCP servers

---

Installation

PILSO OS is distributed via NPM as a zero-config CLI tool.

Run this in your terminal:

npx pilso

The first time you run it, it will:

• Create a working directory .pilso/

• Prompt you to select a model provider (Claude, GPT-4, etc)

• Generate a starter config file

• Guide you through adding a role (e.g. signer, deployer)

---

First-time Setup

After running npx pilso, it will ask:

• Which LLM provider to use

• Your API key

• The role name and tools you want to expose

• Whether to auto-approve trusted tools (for CLI speed)

At the end, you’ll have:

.pilso/
├── pilso.config.json
├── pilso-roles.json
└── session-logs/

---

File Structure Overview

pilso.config.json

Main project config: model settings, tool endpoints, logging behavior, and MCP server connections.

{
  "provider": "claude",
  "apiKey": "sk-xxx",
  "tools": [
    "http://localhost:3020", // metamask-mcp
    "http://localhost:3030"  // erc20-mcp
  ],
  "logLevel": "debug",
  "alwaysAllow": ["metamask.sign"]
}

pilso-roles.json

Defines agent roles and their capabilities:

{
  "signer": {
    "description": "Handles wallet signatures only.",
    "tools": ["metamask.sign"],
    "guardrails": ["never deploy", "never send tokens"]
  }
}

session-logs/

Each agent session is logged here for debugging, auditing, and replay.

---

Starting a Session

Once your config and roles are defined, you can start a PILSO session with:

npx pilso start -r signer

This will:

• Load the signer role

• Connect to your configured LLM

• Initiate the CLI agent runtime

You'll then see:

🤖 Agent ready: signer
💬 > What would you like to do?

From here, type any natural language instruction (e.g. “Sign this transaction”, “Approve USDC”), and the agent will handle tool orchestration — stopping at your wallet for signing approval.

---

MCP Server Setup

By default, PILSO will look for local MCP servers running at the ports defined in pilso.config.json.

You can:

• Run MCP servers (like metamask-mcp, erc20-mcp, chainlist-mcp)

• Clone and customize them

• Host your own on a remote machine or container

Each server must expose a tool schema and support POST requests for execution. More on this in the MCP Server Models section.

---

TL;DR CLI Quickstart

# Install & run
npx pilso

# Start a session with a role
npx pilso start -r signer

# View your active roles or sessions
npx pilso roles
npx pilso sessions list