# permahost.io

> permahost.io is permanent file hosting built for AI agents. An agent uploads static files (HTML, CSS, JavaScript, images, PDFs) into a folder and gets back public URLs that stay up until the folder is deleted, optionally on a custom domain. Hosting is paid for with a monthly credit grant.

- Access: the MCP (Model Context Protocol) server at https://mcp.permahost.io/mcp (one tool, `file`, with the actions upload, download, get, url, list; OAuth sign-in; manifest: https://permahost.io/.well-known/mcp.json) and the `permahost` CLI (`permahost login`, then `permahost file upload <path>`). Docs (Markdown): https://permahost.io/docs.md (source: https://github.com/tmphost/permahost)
- Web app and API: https://app.permahost.io (HTTP API at https://app.permahost.io/api/v1)
- Static files only; no server-side code execution.
- Folders never expire while the account has credits. If a monthly renewal leaves the balance below zero, the account's sites answer HTTP 402 until a later renewal; nothing is deleted.
- Operated by Contextual, Inc., a Delaware corporation. Contact: hi@permahost.io

## Credits

- A folder: 500 credits a month, charged when it is created. Only an upload without a folder id creates one.
- Uploading into an existing folder (MCP `id`, CLI `--id`) never costs folder credits again, however many files it adds or replaces.
- Storage: 500 credits a month per started 25 MB the account stores, charged when an upload starts a block not yet paid for this month; most uploads cost 0.
- A custom domain: 500 credits setup + 500 a month, charged when its CNAME record is verified.
- So: to publish a site, upload the first file without an id, keep the id, and pass it for every other file. To update something published earlier, find its folder (MCP `list`, `permahost file ls`) and upload into it; a file at the same path is replaced in place and keeps its URL.

## Prefer the CLI for token efficiency

If the agent can run shell commands, use the `permahost` CLI instead of the MCP tool. The MCP tool sends file content inline (`base64Content` or `textContent`), so every uploaded or downloaded byte passes through the model's context. The CLI reads and writes files on disk and prints only the URLs, so a large file or a whole directory costs a few tokens.

- Install (macOS/Linux): `curl -fsSL https://raw.githubusercontent.com/tmphost/permahost/main/install.sh | sh`
- Install (Windows PowerShell): `irm https://raw.githubusercontent.com/tmphost/permahost/main/install.ps1 | iex`
- Sign in once: `permahost login` (over SSH or without a browser it prints a link and a code: `permahost login --device`)
- Upload a file or a directory's contents: `permahost file upload report.pdf` or `permahost file upload site/`
- Add to or update an existing folder: `permahost file upload site/ --id <id>`; list folders with `permahost file ls`
- Custom domain: `permahost domain add --id <id> www.example.com`, create the printed CNAME record, then `permahost domain verify --id <id> www.example.com`
- Add `--json` for machine-readable output (`id`, `url`, `creditsSpent`, `files`, ...).
- Download to disk, not stdout: `permahost file download --id <id> <fileName> -o <out>`
- Credits, usage and prices: `permahost whoami`

Only when the CLI can't be installed, call the HTTP API with curl and a Bearer token: see https://permahost.io/docs/api.md.

Use the MCP server when the agent has no shell, or when the content already sits in its context. For text files (HTML, CSS, JS, Markdown, JSON, SVG) pass `format: "textContent"` and send the text as is: it is a third smaller than base64. Keep `base64Content` for binary files.

## Pages

- [Home](https://permahost.io/): what permahost.io is, how it works, pricing, MCP and CLI
- [Docs](https://permahost.io/docs.md): CLI or MCP, and the concepts: folders, ids and URLs, paths, updates, credits (HTML: https://permahost.io/docs/)
- [MCP tool](https://permahost.io/docs/mcp.md): the `file` tool's actions, arguments, results, credits, errors and example calls (HTML: https://permahost.io/docs/mcp/)
- [CLI](https://permahost.io/docs/cli.md): local paths, install, sign in and every `permahost` command with example output (HTML: https://permahost.io/docs/cli/)
- [curl and the HTTP API](https://permahost.io/docs/api.md): every /api/v1 call with curl and a Bearer token, errors and endpoints (HTML: https://permahost.io/docs/api/)
- [Custom domains](https://permahost.io/docs/domains.md): serve a folder on your own hostname: add it, create the CNAME record, verify, HTTPS, cost, troubleshooting (HTML: https://permahost.io/docs/domains/)
- [Plugins](https://permahost.io/docs/plugins.md): install permahost.io in Claude Code, Codex, Cursor or Gemini CLI; adds the MCP server and a skill or context file; OAuth sign-in on first use (HTML: https://permahost.io/docs/plugins/)
- [Claude Code plugin](https://permahost.io/docs/plugins/claude.md): `/plugin install permahost --marketplace tmphost/permahost` (HTML: https://permahost.io/docs/plugins/claude/)
- [Codex plugin](https://permahost.io/docs/plugins/codex.md): `codex plugin marketplace add tmphost/permahost`, then `codex plugin add permahost@permahost` (HTML: https://permahost.io/docs/plugins/codex/)
- [Cursor plugin](https://permahost.io/docs/plugins/cursor.md): Cursor Marketplace or the tmphost/permahost team marketplace; MCP server, skill, rule, `/share-file` and `/share-site` (HTML: https://permahost.io/docs/plugins/cursor/)
- [Gemini CLI extension](https://permahost.io/docs/plugins/gemini.md): `gemini extensions install https://github.com/tmphost/permahost`, policy file to allow the tools (HTML: https://permahost.io/docs/plugins/gemini/)
- [FAQ](https://permahost.io/faq/): common questions about permahost.io
- [Privacy Policy](https://permahost.io/privacy/): what data is collected and how long it is kept
- [Terms of Service](https://permahost.io/tos/): credits, acceptable use, paused sites, liability

## Discovery

- Page index: https://permahost.io/webmcp/pages.json lists every page with its title, description and Markdown URL. In a browser with WebMCP, every page also registers the tools searchPages, lookupPage and navigate (https://permahost.io/.well-known/webmcp.json).
- Agentic Resource Discovery (ARD): https://permahost.io/.well-known/ard.json lists the MCP server and the permahost skill as ARD entries.
- API catalog (RFC 9727): https://permahost.io/.well-known/api-catalog points to the /api/v1 docs.