# fil

> fil stores files and folders on Filecoin and returns links to share them, through a CLI, a read-only MCP server, or a web app with WebMCP tools for browser agents.

**Pick a way in.** Each kind of agent has one:

- Agents with a shell, local or in the cloud, install the agent skill: `npx skills add https://fil-app.hugomrdias.dev`. It covers storing, retrieving, and verifying with the CLI.
- Browser agents open [fil-app](https://fil-app.hugomrdias.dev/). Its WebMCP tools read the account and prepare the wallet owner's approval.
- Agents that only call remote tools add the read-only MCP server at `https://fil-api.hugomrdias.dev/mcp`, over Streamable HTTP. It cannot store content.

A person owns the wallet and approves every agent, which never holds the wallet key. [Agents](https://fil-app.hugomrdias.dev/agents.md) explains each way in. This is a prototype that runs on the calibration test network by default.

## Docs

- [Overview](https://fil-app.hugomrdias.dev/index.md): Store files and folders on Filecoin from a terminal or an agent, and get links back.
- [Quickstart](https://fil-app.hugomrdias.dev/docs/quickstart.md): Install fil, log in, store a file, and download it again on the calibration network.
- [CLI](https://fil-app.hugomrdias.dev/docs/cli.md): How fil works: log in, check the account, store, retrieve, delete, resume, and read its JSON output.
- [Retrieve and verify](https://fil-app.hugomrdias.dev/docs/retrieve.md): What the PieceCID, the root CID, and each retrieval link check, how to find stored content, and how to store without the CLI.
- [Agents](https://fil-app.hugomrdias.dev/agents.md): The way in for each kind of agent: local, cloud, browser, or chat app with connectors, and how the wallet owner approves its key.
- [API and MCP](https://fil-app.hugomrdias.dev/docs/api.md): fil-api retrieval redirects, MCP tools, conventions, and rate limits. The OpenAPI document lists the routes.
- [Web app](https://fil-app.hugomrdias.dev/docs/app.md): The explorer, the wallet dashboard, setup links, and the WebMCP tools in fil-app.

## Optional

- [OpenAPI document](https://fil-api.hugomrdias.dev/openapi.json): fil-api REST API, OpenAPI 3.1
- [MCP server card](https://fil-app.hugomrdias.dev/.well-known/mcp/server-card.json): fil-api MCP server, Streamable HTTP
- [Agent skill: fil](https://fil-app.hugomrdias.dev/.well-known/agent-skills/fil/SKILL.md): Store files and folders on Filecoin with the fil CLI, return links to share them, and retrieve and verify them later. Use when the user asks to publish, store, share, back up, retrieve, or verify content on Filecoin.


# fil

`fil` stores files and folders on [Filecoin](https://docs.filecoin.cloud/) and returns links you can share. People run it in a terminal, and agents run it in a shell. Every command writes one JSON result that an agent can act on.

This is a prototype. It runs on the calibration test network unless you choose mainnet.

## Ways to use it

- **CLI.** `fil put ./site` stores a folder and returns a browser link. `fil get` downloads and verifies it. See the [CLI docs](/docs/cli).
- **MCP server.** `https://fil-api.hugomrdias.dev/mcp` gives agents read-only tools for providers, data sets, pieces, payment rails, and session keys. See [API and MCP](/docs/api).
- **Web app.** [fil-app](https://fil-app.hugomrdias.dev) is an explorer for that data and a wallet dashboard for funding storage and approving keys. See [Web app](/docs/app).

## How an agent gets access

The agent never holds the wallet key. It gets a session key, which the wallet owner approves in fil-app and which cannot move funds. [Agents](/agents) shows the way in for each kind of agent: local, cloud, browser, or chat app.

## Start

- [Quickstart](/docs/quickstart): install the CLI, log in, and store a file.
- [Agents](/agents): add `fil` to Claude, ChatGPT, or another agent.
- [Source code](https://github.com/hugomrdias/fil) on GitHub.


# Quickstart

This guide installs `fil`, logs in, stores a file, and downloads it again. It uses the calibration test network, so storage is paid with test USDFC.

You need:

- Node.js 24 or newer.
- A browser wallet, such as MetaMask, with calibration FIL for gas and test USDFC. The [Filecoin docs](https://docs.filecoin.cloud/) list the faucets.

## Hand it to an agent

Add fil to your agent, then ask it to store a file. On its first run, the agent sends you a link to approve its key with your wallet. [Agents](/agents) covers cloud and browser agents.

<!-- tabs -->

### Install the plugin

```sh
claude plugin marketplace add hugomrdias/fil
claude plugin install fil@fil

# In Codex
codex plugin marketplace add hugomrdias/fil
codex plugin add fil@fil
```

Adds the agent skill and the read-only MCP server to Claude Code or Codex.

### Install the agent skill

```sh
npx skills add https://fil-app.hugomrdias.dev
```

Teaches any agent with a shell when and how to run `fil`.

### Connect the MCP server

```sh
npx -y add-mcp https://fil-api.hugomrdias.dev/mcp -g
```

Read-only tools for providers, data sets, and pieces. It cannot store files.

<!-- /tabs -->

To do it yourself, follow the steps below.

## Install the CLI

```sh
npm install -g @hugomrdias/fil
fil --help
```

## Log in

```sh
fil login
```

`fil login` makes a session key, saves it on your machine, and opens the fil-app setup page. Connect your wallet there, review the request, and approve each step. The page can also approve Warm Storage and deposit USDFC. The private key never leaves your machine, and the CLI finds the approval on chain, so there is nothing to copy back.

Then check the account:

```sh
fil status
```

`fil status` reports when each permission expires, your USDFC funds, and the Warm Storage approval. If the account needs a deposit, it also returns a funding link.

## Store a file

Check the size, provider, and cost first. A dry run stores nothing:

```sh
fil put ./report.pdf --dry-run
```

Then store it:

```sh
fil put ./report.pdf
```

The result's `urls.browser` is the link to share. A new link to a file can return 404 for a while. [Retrieve and verify](/docs/retrieve) explains why, and what each link checks.

## Get it back

```sh
fil ls
fil get res_… --output ./copy.pdf
```

`fil get` downloads from the provider and checks the bytes against the PieceCID.

## Next

- [CLI](/docs/cli) explains how `fil` works and where its help and schemas are.
- [Agents](/agents) shows how to give an agent the same access.


# CLI

`fil` stores a file or a folder as one copy on one storage provider and returns retrieval links. It runs on the calibration network unless you choose mainnet. It needs Node.js 24 or newer:

```sh
npm install -g @hugomrdias/fil
```

Or run it without installing, as `npx -y @hugomrdias/fil`.

This page explains how `fil` works. The CLI describes its own commands, which always match the installed version:

- `fil --help` lists the commands, and `fil <command> --help` shows examples and flags.
- `fil schema <command>` prints the command's input and output as JSON Schema, and what each error code means. `fil schema --list` lists every command with its side effects.

## Log in

```sh
fil login
```

`fil login` makes a session key and saves it on your machine. It then opens the [fil-app](https://fil-app.hugomrdias.dev) setup page with the key's address. The wallet owner reviews the request there and approves it with their wallet. The CLI finds the approval on chain, so there is nothing to copy back.

By default, `fil login` asks for the `createDataSet`, `addPieces`, and `schedulePieceRemovals` permissions for 30 days, under the name `fil-cli`. Repeat `--scopes` to ask for others. `--name` sets the name the owner sees, which is recorded on chain, and `--days` sets the expiry. The owner can change all three on the page before approving.

The session key signs each request, the provider submits the transactions, and the wallet pays for storage.

In a terminal, `fil login` opens the browser and waits for approval. An agent, or any run without a terminal, gets a `login_pending` error instead and never waits. The error's `next` steps are the approval link for the user and `fil login --check` for the agent to run after the user approves. `--check` only confirms the saved key and never makes a new one.

Running `fil login` again never changes a saved key's request: flags you leave out keep its scopes, name, and expiry. An interrupted login resumes with the same key, and an approved key is reused when it has the requested permissions. `fil login` replaces a saved key on its own only when the key has expired. If `--scopes` asks for more than a pending or valid key has, you get a `session_conflict` error and the key stays, because the owner may already have approved it. Pass `--fresh` to replace it.

For CI or a [cloud agent](/agents#cloud-agents), set `FIL_SESSION_KEY` and `FIL_ROOT_ADDRESS` instead of running `fil login`.

## Check the account

The session key cannot fund the account. `fil status` reports when each permission expires, the USDFC funds, and the Warm Storage approval. When the account needs a deposit, it also returns a prefilled funding link to the fil-app setup page.

`fil doctor` shows the network, RPC, fil-app and fil-api origins, and state directory that `fil` uses, with where each value came from.

## Store and retrieve

```sh
fil put ./report.pdf          # a file, stored as its exact bytes
fil put ./site                # a folder, packed into a UnixFS CAR
fil put ./site --dry-run      # size, provider, cost, and authorization; stores nothing
fil publish ./site            # same as put
fil get res_… --output ./copy # verifies the PieceCID and extracts folders
fil ls                        # add --all to include content pending removal
fil inspect res_… --check     # checks that the piece link answers
fil delete res_… --yes        # same as rm; schedules removal
```

`put` returns `urls.browser`, the link to share, and `urls.piece`, the exact stored bytes. [Retrieve and verify](/docs/retrieve) explains what each link and `fil get` check.

Packing skips dotfiles and rejects symlinks. The file, or the packed folder, must be between 127 bytes and 1,065,353,216 bytes (1016 MiB).

`delete` schedules removal, and the provider then deletes the stored copy. The content's state becomes `removal_pending`. Without `--yes`, `delete` asks a person at a terminal to confirm. Everyone else, including agents, gets `confirmation_required` with a step for the user.

## Resume an interrupted put or delete

```sh
fil operations ls --incomplete
fil operations inspect op_…
fil operations resume op_…
```

Each `put` and `delete` saves an operation before it changes anything, and prints its ID to stderr at once. An error from a put or a delete carries a `fil operations resume <id>` step. Run that step instead of the original command, which would start a new paid operation.

A resumed put never stores or pays twice:

- It skips the upload when the provider already has the piece.
- It checks on chain whether the commit landed before it sends it again.
- It fails with `source_changed` when the source file changed.
- It returns the saved result of an operation that already completed.

Ctrl+C stops the work at the next step and returns an `interrupted` result with the resume step.

## Output and errors

When an agent runs `fil`, or when you pass `--json` or redirect stdout, `fil` writes one JSON object to stdout: `data` on success or `error` on failure, then optional `next` steps. The exit code is `0` with `data` and `1` with `error`. Progress goes to stderr.

Each error has a stable `code`, and `fil schema <command>` lists the codes the command returns and what they mean. Errors that need a person, such as `login_pending` and `insufficient_funds`, carry a `next` step with a fil-app link for the user.

## Configuration

| Variable | Purpose |
| --- | --- |
| `FIL_NETWORK` | `mainnet` or `calibration`. `--network` wins, then `FIL_NETWORK`, then the config file, then `calibration` |
| `FIL_SESSION_KEY`, `FIL_ROOT_ADDRESS` | Session key and wallet address, used instead of `fil login` |
| `FIL_CONFIG_DIR` | Config directory. Default: the platform config directory for `fil` |
| `FIL_STATE_DIR` | Local state and staged folders. Default: the platform data directory for `fil` |
| `FIL_RPC_URL` | RPC endpoint |
| `FIL_CONSOLE_URL` | fil-app origin for approval and funding links. Default: `https://fil-app.hugomrdias.dev` |
| `FIL_API_URL` | fil-api origin for retrieval links. Default: `https://fil-api.hugomrdias.dev` |
| `FIL_OUTPUT`, `FIL_AGENT` | Override the output mode and agent detection |

The prototype saves the session key in the config file, readable only by its owner. `fil logout` deletes the local key. The key stays authorized on chain until it expires or you revoke it on the fil-app [session keys page](https://fil-app.hugomrdias.dev/dashboard/session-keys).


# Retrieve and verify

Everything `fil` stores has a PieceCID, and a folder also has a root CID:

- The **PieceCID** (`bafkzcib…`) identifies the exact stored bytes. The storage provider proves on chain that it still holds them.
- The **root CID** identifies a folder on IPFS. `fil` packs a folder into a UnixFS CAR, and the PieceCID covers that CAR.

`fil put` returns two links on fil-api's [`/get/{cid}` route](/docs/api#retrieval), which redirects to a provider that stores the content:

- `urls.browser` is the link to share. A browser renders a file straight from the provider, and opens a folder through [inbrowser.link](https://inbrowser.link).
- `urls.piece` returns the exact stored bytes.

fil-api finds providers through its indexer, so a new piece link returns 404 until the indexer has the piece. `fil inspect <ref> --check` reports when the piece link answers.

While the commit confirms, `fil put` prints an early browser link to stderr as `fil: link: <url>`:

- **A file's early link** works as soon as the provider has the piece. It names the provider, so fil-api can redirect before its indexer catches up.
- **A folder's early link** comes once the commit is sent. It starts working shortly after, when the provider has indexed the folder and announced it to IPFS.

## What each way checks

| Way | Who can use it | Gets | Checks |
| --- | --- | --- | --- |
| `fil get <ref>` | Agents with a shell, and people | A file, or the folder, extracted | The bytes against the PieceCID, and for a folder the root CID. On a mismatch it keeps nothing and fails with `verification_failed` |
| `fil get <PieceCID>` | Agents with a shell, and people | The stored bytes as one file. For a folder, that is the CAR | The bytes against the PieceCID |
| A folder's `urls.browser` | Browser agents, and people | The folder, rendered | Each block, in the browser |
| A file's `urls.browser`, or `urls.piece` | Anything that speaks HTTP | The bytes | Nothing |

Use `fil get` when the content must be intact. When you hand over a link that checks nothing, say so.

## Find stored content

`fil ls` lists what this machine stored. The list lives in a local database, so a new machine, or a cloud sandbox that was reset, starts empty. The content is still on Filecoin, under the wallet that paid for it:

- In a browser, the dashboard's data sets page, or the WebMCP tools `list_data_sets` and `list_pieces`.
- Over MCP, `list_pieces` with the wallet as `owner`. Over HTTP, `GET /{network}/pieces?owner=<wallet>` on fil-api.

Each piece comes with a retrieval link. `fil get <PieceCID>` downloads and checks one with the same wallet's session key.

## Store without the CLI

The dashboard's [upload page](/dashboard/upload) stores files in one of the wallet's data sets. The wallet signs each step, so a person must be at the browser. It stores files, not folders. The MCP server and the REST API cannot store anything.


# Agents

Pick the way in that matches what your agent can do. In every case, a person owns the wallet and approves what the agent may do, and the agent never holds the wallet key.

| Agent | What it can do | Way in |
| --- | --- | --- |
| Local agent, such as Claude Code, Codex, or Cursor | Run a shell, keep files, and open pages for you | [Plugin, or CLI and agent skill](#local-agents) |
| Cloud agent, such as a coding agent in a hosted sandbox | Run a shell, but its files are gone when the session ends | [CLI with a key from secrets](#cloud-agents) |
| Browser agent | Read and use web pages in the browser that holds your wallet | [fil-app's WebMCP tools](#browser-agents) |
| Chat app with connectors, such as Claude or ChatGPT | Call remote tools | [MCP server](#mcp-server), read-only |

[Retrieve and verify](/docs/retrieve) compares what each way can store, retrieve, and check.

## Local agents

In Claude Code and Codex, install the fil plugin. It adds the agent skill and the read-only [MCP server](#mcp-server) in one step. In Claude Code:

```sh
claude plugin marketplace add hugomrdias/fil
claude plugin install fil@fil
```

In Codex:

```sh
codex plugin marketplace add hugomrdias/fil
codex plugin add fil@fil
```

The plugin follows the [Agent Plugins](https://agent-plugins.org) format, so other agents that support it can load it from the repository's [`plugins/fil`](https://github.com/hugomrdias/fil/tree/main/plugins/fil) directory.

In other agents, install the agent skill. It tells the agent when to use `fil`, the workflow, and the rules, and points it to the CLI's own help, which always matches the installed version:

```sh
npx skills add https://fil-app.hugomrdias.dev
```

`npx skills add hugomrdias/fil` installs the same skill from GitHub. Agents that support [agent skills discovery](https://github.com/cloudflare/agent-skills-discovery-rfc) find it at [`/.well-known/agent-skills/index.json`](/.well-known/agent-skills/index.json).

The agent runs the CLI with `npx -y @hugomrdias/fil`, which needs Node.js 24 or newer. To install it instead, run `npm install -g @hugomrdias/fil`. Then `fil skills install` installs the copy of the skill that matches the installed CLI.

The first `fil login` asks you to [approve the agent's key](#approve-the-agents-key).

## Cloud agents

A cloud agent has a shell, so it uses the same skill and CLI as a local agent. It has no browser to open for you, and its disk is gone when the session ends. `fil login` saves the session key on that disk, so each session would ask you to approve a new key.

Give the agent a key that outlives the session instead:

1. On the fil-app [session keys page](https://fil-app.hugomrdias.dev/dashboard/session-keys), generate a session key, authorize it, and export it.
2. In the agent's environment settings, add the key as the secret `FIL_SESSION_KEY`, and your wallet address as `FIL_ROOT_ADDRESS`.

`fil` then skips `fil login`, and `fil status` confirms the key works. The key cannot move funds, and it expires. Revoke it on the same page to stop the agent. Never paste the key into a chat.

`fil ls` and `fil operations` read a local database, which a new session starts without. [Find stored content](/docs/retrieve#find-stored-content) shows how to look it up by wallet.

## Browser agents

fil-app registers [WebMCP](https://webmachinelearning.github.io/webmcp/) tools. A browser agent can prepare a setup request without building a URL, and read the account, its data sets and pieces, and its session keys. The tools never sign anything, and they describe themselves to the agent. [Web app](/docs/app#webmcp-tools) lists them. WebMCP is an early preview that works in Chrome 149 and later. Without it, the agent opens a [setup link](/docs/app#setup-links).

A browser agent cannot run the CLI. You can store files from the dashboard's upload page while it watches, and a folder's link verifies in the browser.

## MCP server

fil-api's MCP server gives any agent read-only tools for storage providers, data sets, pieces, Filecoin Pay rails, and session keys, on mainnet and calibration. It uses Streamable HTTP and needs no authentication. It cannot store or delete content.

```text
https://fil-api.hugomrdias.dev/mcp
```

The [fil plugin](#local-agents) adds it in Claude Code and Codex. To add the server alone, [add-mcp](https://github.com/neon-solutions/add-mcp) writes it into the configuration of Claude Code, Codex, Cursor, VS Code, and about 20 other agents:

```sh
npx -y add-mcp https://fil-api.hugomrdias.dev/mcp
```

It asks which agents to configure, and adds the server to the current project. Add `-g` to add it for your user instead.

Claude Code and Codex also add it with their own commands:

```sh
claude mcp add --transport http fil-api https://fil-api.hugomrdias.dev/mcp
codex mcp add fil-api --url https://fil-api.hugomrdias.dev/mcp
```

In the Claude and ChatGPT apps, add the URL as a custom connector. [API and MCP](/docs/api#mcp-server) lists the tools.

## Approve the agent's key

The agent never holds the wallet key. It gets a session key instead, and the wallet owner approves it:

1. The agent runs `fil login`. It gets a `login_pending` error with an approval link, and relays the link to you.
2. You open the link, connect your wallet, and review the request on the fil-app setup page. Approve the session key, the Warm Storage approval, and a USDFC deposit if the page asks for them.
3. The agent runs `fil login --check` to confirm, then `fil put`. `--check` never makes a new key, so it can't replace the one you approved.

When the account runs low, `fil status` and `fil put` return `insufficient_funds` with a prefilled funding link for you. To stop the agent, revoke its key on the fil-app [session keys page](https://fil-app.hugomrdias.dev/dashboard/session-keys).

## Discovery files

This site describes itself to agents:

| Path | Contents |
| --- | --- |
| [`/llms.txt`](/llms.txt) | An index of these docs in Markdown, from [llmstxt.org](https://llmstxt.org) |
| [`/llms-full.txt`](/llms-full.txt) | Every docs page in one Markdown file |
| [`/.well-known/api-catalog`](/.well-known/api-catalog) | Links to fil-api's OpenAPI document, reference, and MCP server, as an [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) API catalog |
| [`/.well-known/integrations.json`](/.well-known/integrations.json) | The REST API, the MCP server, and the CLI, with what each needs to authenticate, for [integrations.sh](https://integrations.sh) |
| [`/.well-known/mcp/server-card.json`](/.well-known/mcp/server-card.json) | The MCP server card, also at `/.well-known/mcp-server-card` |
| [`/.well-known/agent-skills/index.json`](/.well-known/agent-skills/index.json) | The agent skills index, with the `fil` skill |
| [`/sitemap.xml`](/sitemap.xml) | Every page, also linked from `/robots.txt` |

Every docs page also has a Markdown version. Add `.md` to the path, such as [`/docs/cli.md`](/docs/cli.md), or send `Accept: text/markdown`:

```sh
curl -H 'Accept: text/markdown' https://fil-app.hugomrdias.dev/docs/cli
```

A request that accepts only Markdown gets a Markdown answer from every page. A missing page returns `404` with links to `llms.txt` and the sitemap. An explorer or dashboard page, which has no Markdown version, returns `406`.


# API and MCP

[fil-api](https://fil-api.hugomrdias.dev) serves read-only Filecoin data: storage providers, data sets, pieces, Filecoin Pay rails, and session keys. It reads from an indexer of the Filecoin chain, so its data trails the chain. `/health` reports the latest indexed block. It cannot store, delete, or sign anything.

The interactive reference is at [`/docs`](https://fil-api.hugomrdias.dev/docs), and the OpenAPI 3.1 document is at [`/openapi.json`](https://fil-api.hugomrdias.dev/openapi.json).

## Routes

`GET /openapi.json` lists every route and its filters, and `POST /mcp` is the MCP server. `GET /health` reports the latest indexed block per network, and [`GET /get/{cid}`](#retrieval) redirects to where content can be retrieved. Every data route starts with the network, `/calibration/...` or `/mainnet/...`, and reads one of: indexer status, storage providers, data sets and their pieces, pieces by owner or PieceCID, Filecoin Pay rails and their settlements, and session keys and their history.

Conventions:

- **Owner** is the address that pays for a data set.
- **Big numbers**, such as IDs, amounts, and epochs, are decimal strings.
- **Pagination** uses `limit` (1 to 200, default 50) and an opaque `cursor`. Each response looks like `{ data, nextCursor }`.
- **Errors** look like `{ error: { code, message } }`.
- **Operation IDs**, such as `listDataSets` and `retrieve`, name every operation in the OpenAPI document, for function calling and generated clients.

## Retrieval

`GET /get/{cid}?network=mainnet&browser=false` redirects to where the content can be fetched. It never proxies the bytes. `network` defaults to `mainnet`.

| CID | `browser` | Redirect |
| --- | --- | --- |
| PieceCID v2 (`bafkzcib…`) | `false` or absent | The provider's `/piece/{cid}` |
| PieceCID v2 (`bafkzcib…`) | `true` | `https://inbrowser.link/ipfs/{root}` when the piece is a folder, otherwise the provider's `/piece/{cid}` |
| Other CID (IPFS content) | `false` or absent | The provider's `/ipfs/{cid}` |
| Other CID (IPFS content) | `true` | `https://inbrowser.link/ipfs/{cid}` |

`provider={id}` names a provider to redirect to when the indexer has no copy yet. It covers the time between a provider receiving a piece and the indexer seeing the commit. An indexed copy always wins over it. `fil put` adds it to the early links it prints before the commit confirms.

Legacy v1 PieceCIDs (`baga…`) and strings that aren't CIDs return `400`. If no live copy exists and no `provider` applies, the response is `404`. When several providers store the content, the route prefers endorsed providers, then approved ones, then the oldest copy.

## MCP server

The MCP server at `https://fil-api.hugomrdias.dev/mcp` offers one read-only tool for each data route. Each tool requires a `network` argument.

| Tool | Reads |
| --- | --- |
| `get_status` | Indexer progress |
| `list_providers`, `get_provider` | Storage providers |
| `list_data_sets`, `get_data_set` | Data sets |
| `list_data_set_pieces`, `get_piece`, `list_pieces` | Pieces |
| `list_rails`, `get_rail`, `list_rail_settlements` | Filecoin Pay rails and settlements |
| `list_session_keys`, `list_session_key_events` | Session keys and their history |

[Agents](/agents#mcp-server) shows how to add it to an agent.

## Limits

- **Rate limits.** 120 requests a minute per IP for the REST API, and 60 for MCP. Over the limit, requests get `429` with `Retry-After`.
- **Caching.** Data reads are not cached by browsers, so every read returns the latest indexed data.
- **No authentication.** Every route is public and read-only.


# Web app

[fil-app](https://fil-app.hugomrdias.dev) has three parts:

- **Explorer** (`/mainnet`, `/calibration`): public pages for data sets, pieces, storage providers, Filecoin Pay rails and settlements, session keys, and each address. Search with `/` or ⌘K from any page.
- **Dashboard** (`/dashboard`): connect a wallet to manage your Filecoin Pay account, the Warm Storage approval, data sets, uploads, rails, and session keys.
- **Setup page** (`/dashboard/setup`): review and approve a request from `fil` or an agent.

## Session keys

A session key lets a tool sign storage requests for your wallet. It can create data sets, add pieces, schedule piece removals, and end service, but it can never move funds. Keys you make in the dashboard stay in this browser. Keys made by `fil login` stay on the agent's machine, and the dashboard only approves them.

The session keys page lists every key your wallet approved, with when each permission expires. Revoke a key there to stop the tool that holds it.

## Setup links

`fil login`, `fil status`, and the `put` funding check send the wallet owner to `/dashboard/setup`. The page fills in the request from the link, and you review it, change what you need, and approve each step with your wallet. Each step is its own transaction, so nothing is signed until you click.

| Parameter | Meaning |
| --- | --- |
| `network` | `mainnet` or `calibration`. The page asks to switch the wallet when it is on the other network |
| `signer` | Session key address to approve. The private key stays with the tool that made it |
| `name` | Session key name, up to 64 characters, recorded on chain. Default: `fil-app` |
| `scopes` | Comma-separated permissions: `createDataSet`, `addPieces`, `schedulePieceRemovals`, `terminateService`. Default: the first three |
| `days` | Days until the approval expires, from 1 to 365. Default: 30 |
| `deposit` | USDFC to deposit, as a decimal amount |

Every parameter is optional, and the page drops an invalid value instead of failing. The Warm Storage step appears whenever the wallet has not approved it.

## WebMCP tools

fil-app registers [WebMCP](https://webmachinelearning.github.io/webmcp/) tools, so a browser agent can prepare a setup request and read the account and its storage:

| Tool | Where | What it does |
| --- | --- | --- |
| `prepare_setup_request` | Every page | Checks a request with the parameters above and opens the prefilled setup page. It never signs anything |
| `get_setup_status` | `/dashboard/setup` | Reports whether a wallet is connected and on Filecoin, and which requested permissions are approved |
| `get_account_summary` | Every page | Reports a wallet's Filecoin Pay funds, monthly spend, runway, and Warm Storage approval |
| `list_data_sets` | Every page | Lists a wallet's data sets |
| `list_pieces` | Every page | Lists a data set's pieces, each with a retrieval link |
| `lookup_piece` | Every page | Finds the data sets that hold a PieceCID v2 |
| `list_session_keys` | Every page | Lists the session keys a wallet approved |

The read tools default to the connected wallet and the network in the page address. WebMCP is an early preview. It works in Chrome 149 and later on fil-app.hugomrdias.dev, and in the ChatGPT desktop app's browser, where the tools are called site tools. Other browsers ignore the tools, and agents use setup links instead.