# Plugins

> A plugin connects Claude Code, Codex, Cursor or Gemini CLI to permahost.io. The plugin adds the MCP server and tells the agent when and how to publish files with it, so a request such as "publish this report and send me the link" just works.

HTML version: https://permahost.io/docs/plugins/ · All docs: https://permahost.io/docs.md

- [**Claude Code**: The `permahost` plugin from the tmphost/permahost marketplace: the MCP server plus a `permahost` skill.](https://permahost.io/docs/plugins/claude.md)
- [**Codex**: The same server and skill as an Agent Plugins package, added with `codex plugin add`.](https://permahost.io/docs/plugins/codex.md)
- [**Cursor**: A Cursor plugin with the MCP server, the `permahost` skill, a rule for publish requests and the `/share-file` and `/share-site` commands.](https://permahost.io/docs/plugins/cursor.md)
- [**Gemini CLI**: A Gemini CLI extension installed from the GitHub repository: the MCP server plus a `GEMINI.md` context file.](https://permahost.io/docs/plugins/gemini.md)

## Install

| Agent | Install | Instructions it adds |
| --- | --- | --- |
| Claude Code | `/plugin install permahost --marketplace tmphost/permahost` | The `permahost` skill |
| Codex | `codex plugin marketplace add tmphost/permahost`, then `codex plugin add permahost@permahost` | The `permahost` skill |
| Cursor | **permahost** from the Cursor Marketplace, or import `tmphost/permahost` as a team marketplace, then enable it in **Cursor Settings → Tools & MCP** | The `permahost` skill, a rule and two commands |
| Gemini CLI | `gemini extensions install https://github.com/tmphost/permahost` | `GEMINI.md`, loaded into every session |

All four come from the public repository [github.com/tmphost/permahost](https://github.com/tmphost/permahost), which is also their marketplace. Each agent's page has the steps, the sign-in and a self-hosted setup. The plugins are licensed under the Apache License 2.0; the permahost server is AGPL-3.0-only.

## What a plugin adds

- **The MCP server** `https://mcp.permahost.io/mcp`, named `permahost`. Its one tool, `file`, has the actions `upload`, `download`, `get`, `url` and `list`: see [MCP tool](https://permahost.io/docs/mcp/).
- **Instructions** on when to use it (host, share, publish or link a file, a report, an image or a static site) and how: send text files as `textContent`, upload a site file by file into one folder, find an existing folder with `list` before adding to it, and never create a folder just to add files.

Nothing runs on your machine besides the agent: the plugin is configuration and text.

## Sign-in

The MCP server needs a permahost.io account. The first tool call answers `401`, the agent finds the OAuth endpoints of app.permahost.io from it, registers itself and opens the browser. Sign in (or sign up: the same page does both) and the agent keeps and refreshes the token. No API key to copy.

Uploads spend the account's monthly credits: 500 a month for each new folder, and 500 a month per started 25 MB the account stores. Adding files to an existing folder never costs folder credits again. See [credits](https://permahost.io/docs/#credits).

## Plugin or CLI?

The plugins work through MCP, so every byte of a file passes through the model's context as a tool argument. That is fine for the HTML page or the Markdown note the agent just wrote. For large files, binary files or whole directories, an agent with a shell does better with the [`permahost` CLI](https://permahost.io/docs/cli/), which reads from disk and prints only the URLs. Claude Code, Codex, Cursor and Gemini CLI all have a shell, so install both if you publish big files: see [CLI or MCP?](https://permahost.io/docs/#which)

## Self-hosted permahost

The plugins point at app.permahost.io. For your own permahost server, skip the plugin and add an MCP server named `permahost` that points at your server's MCP URL instead. Each agent's page shows how.