# Install & Launch

This guide covers how to install and launch **PILSO OS** locally via the CLI.\
PILSO is distributed as a Node.js [CLI tool that co](#user-content-fn-1)[^1]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:

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

```plaintext
.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.

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

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

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

```plaintext
🤖 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**](/mcp-server-models/metamask-mcp-signing.md) section.

***

### TL;DR CLI Quickstart

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

[^1]:


---

# 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/quickstart/install-and-launch.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.