Skip to main content
Glama

pushpage

An HTML page publishing service for AI agents. AI agents POST HTML content and get a shareable URL back instead of dumping text into chat.

Why this project exists

AI agents are increasingly capable of generating rich, complex outputs, but they have been missing a key piece: a way to publish and share that output. pushpage is that missing piece. Instead of dumping walls of text or Markdown into chat, an agent can POST HTML to pushpage and hand back a clean, shareable URL.

This project was directly inspired by The Unreasonable Effectiveness of HTML by Thariq Shihipar (Claude Code team). The core insight: HTML is a dramatically more effective medium for AI-generated output than Markdown.

Why HTML beats Markdown for human consumption:

  • Markdown is a plaintext approximation. Large documents become walls of text that people skim or abandon. HTML lets agents express the same information with visual hierarchy, tabs, tables, and illustrations that readers actually engage with.

  • HTML is interactive. Sliders, toggleable sections, copy buttons, real-time previews. None of that is possible in Markdown. A spec or report that lets the reader interact with it closes the feedback loop far faster.

  • HTML is shareable. A clickable link gets reviewed; a .md attachment does not. pushpage turns every agent output into a URL a human can actually open.

pushpage gives AI agents a publish endpoint so that the richer, more effective HTML output format is no longer a dead end. It becomes something you can share with a single link.

Related MCP server: dochost

API

All endpoints are under /api (Spring Boot context path). Most require an API key via X-Api-Key: <key> or Authorization: Bearer <key>.

Method

Path

Auth

Description

POST

/api/pages

Optional

Publish HTML (JSON or file upload), returns { url, id }

GET

/api/health

None

Health check

GET

/api/config

None

Public frontend config (enabled feature flags)

For the full API reference — page management, admin user endpoints, request/response schemas — see the Swagger UI: https://pushpage.link/api/swagger-ui/index.html

Deployment

Prerequisites

  • Docker and Docker Compose

  • A .env file in the project root. The one required variable is APP_SERVER_URL, which must match the URL where the service will be accessible. Set it to http://localhost:8080 to get started quickly, or to a custom hostname if you have DNS set up for it. If you'd rather skip self-hosting, a managed public instance is available at https://pushpage.link — it runs this exact same open-source image, just with the PLANS_ENABLED and EMAIL_ENABLED feature flags turned on (see docs/configuration.md) to enable subscription plans and email (sign-up verification and password-reset emails).

APP_SERVER_URL=http://localhost:8080

All other variables have sensible defaults. See docs/configuration.md for the full list.

Running

Create the data directories, then pull the pre-built images and start the stack:

mkdir -p data/pages data/pgdata
docker compose up -d

Verify the service is running:

curl https://pushpage.link/api/health

Or open the Swagger UI in a browser: https://pushpage.link/api/swagger-ui/index.html

Or open the dashboard: https://pushpage.link/dashboard

To stop the stack:

docker compose down

To wipe all published pages and metadata:

docker compose down -v

Getting Started

1. Get your API key

On first run, if the database has no users, the service automatically creates an admin user and logs its API key once:

==============================================================
No admin user found — bootstrap admin created.
API Key: pp_abc123...
Copy this key now. It will NOT appear again after restart.
==============================================================

Copy that key — you'll use it in the next step.

2. Open the dashboard (optional)

Navigate to https://pushpage.link/dashboard (or your self-hosted equivalent) and enter your API key. The dashboard lets you browse and delete your pages, view account info, and (as admin) manage users — all without touching the API directly.

3. Publish your first page

You can start publishing immediately with the admin key. No extra setup required.

curl -X POST https://pushpage.link/api/pages \
  -H "X-Api-Key: pp_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"html": "<html><head><title>My Report</title></head><body><h1>Hello</h1><p>Some content here.</p></body></html>"}'

Response:

{
  "url": "https://pushpage.link/pages/a1b2c3d4.html",
  "id": "a1b2c3d4"
}

Open the url in your browser — that's your published page.

POST /api/pages also works without an API key — guest pages auto-expire after 30 minutes and are not tied to any account, ideal for quick one-off shares.

4. Create a dedicated user (optional)

The admin key is enough for a single-agent or personal setup. If you want to give a separate key to a different agent or user (so their pages are scoped independently), create a dedicated user:

curl -X POST https://pushpage.link/api/admin/users \
  -H "X-Api-Key: pp_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"username": "myagent", "email": "agent@example.com", "admin": false}'

Response — save the api_key, it is only shown once:

{
  "id": "a1b2c3d4",
  "username": "myagent",
  "email": "agent@example.com",
  "api_key": "pp_xyz789...",
  "created_at": "2026-01-01T00:00:00Z",
  "admin": false
}

That user can now publish pages with their own key. Regular users only see their own pages in GET /api/pages; admins see all.

Agent Integration

Skill file

The skill/ directory contains a skill file (skill/SKILL.md) for use with AI agent frameworks such as Claude Code. Loading this skill tells the agent how to interact with pushpage: when to publish, how to structure the HTML, and how to return the resulting URL to the user.

Once the skill is loaded, the agent will automatically publish rich HTML output to pushpage instead of dumping content into chat, and return a clickable link.

See skill/SKILL.md for the full skill definition and usage examples.

llms.txt

llms.txt is served at https://pushpage.link/llms.txt (or {APP_SERVER_URL}/llms.txt for self-hosted instances) and follows the llms.txt convention — a plain-text file that describes what a service does and how to interact with it. An agent that discovers the pushpage instance via HTTP can read this file to understand the API, authentication, and typical usage flow without any prior configuration.

MCP Server

pushpage ships a cloud MCP server that lets any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.) publish, list, and delete pages — no local install required. Agents connect to it with a single URL.

The MCP server starts automatically with the rest of the stack — no extra configuration needed:

docker compose up -d

Once running, the server is available at https://pushpage.link/mcp (or {APP_SERVER_URL}/mcp for self-hosted instances). Each client supplies their own pushpage API key via the Authorization header.

Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "pushpage": {
      "url": "http://your-domain/mcp",
      "headers": {
        "Authorization": "Bearer pp_your_key_here"
      }
    }
  }
}

Claude Code CLI:

claude mcp add --transport http pushpage http://your-domain/mcp \
  --header "Authorization: Bearer pp_your_key_here"

Storing your key: keep it in ~/.config/pushpage/credentials (chmod 600) and, where your client supports it (Claude Code, Cursor), reference it as an environment variable instead of pasting it into config. Details in docs/mcp.md.

The MCP server can also run locally over stdio (python mcp/server.py --stdio with PUSHPAGE_API_KEY set); see docs/mcp.md.

For the full tool reference, alternative connection methods (including mcp-remote for HTTP-only or older clients), and troubleshooting, see docs/mcp.md.

Security

Published pages are served with a Content-Security-Policy: sandbox header (without allow-same-origin), so scripts in a page cannot access the dashboard session or call the API on a viewer's behalf. The dashboard cannot be framed, and login/signup are rate-limited per IP by nginx, and dot-prefixed paths such as /.env are never served. Behind a reverse proxy or tunnel, set TRUSTED_PROXIES (and REAL_IP_HEADER) so rate limits use the real client IP. Details in docs/configuration.md.

Database

pushpage uses PostgreSQL. docker-compose.yml starts a co-located postgres:17-alpine container automatically — no extra setup required.

To point at an external PostgreSQL instance instead, override the connection variables in your .env:

DB_HOST=your-postgres-host
DB_NAME=pushpage
DB_USER=pushpage
DB_PASSWORD=changeme

See docs/configuration.md for the full variable reference.

Contributing / Local Development

To build from source and run locally:

docker compose -f docker-compose.dev.yml up -d --build

This starts a PostgreSQL container alongside the publisher (using tmpfs, so data is not persisted between restarts).

Available Tools

4 tools
delete_pageDelete PageB

Delete a page by its id.

Use the id from publish_page or list_pages.

Inputs: id (required). Returns: object

healthHealthA

Check whether the pushpage service is reachable and healthy.

Inputs: no named parameters. Returns: object

list_pagesList PagesA

List all pages published by the current user.

Returns a list of page objects, each with id, title, url, and created_at.

Inputs: no named parameters. Returns: result

publish_pagePublish PageA

Publish an HTML page and return its shareable URL.

Returns {url, id, expires_at}. title is optional — when omitted it is extracted from the HTML tag, or falls back to 'Untitled'. expires_at is an ISO-8601 timestamp indicating when the page will be automatically deleted.

Inputs: html (required), title. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a clearly distinct action: publish (write), list (read), delete (remove), and health (service check). There is no overlap in purpose, so an agent can select unambiguously from names and descriptions alone.

    Naming Consistency4/5

    publish_page, list_pages, and delete_page all follow a clean verb_noun pattern on the same resource. health is a bare noun with no verb, a small but noticeable deviation from the otherwise consistent convention.

    Tool Count5/5

    Four tools is well-scoped for a simple page-publishing service; every tool (including the health check) earns its place with no filler or redundancy.

    Completeness3/5

    The surface covers create, list, and delete, but there is no update/republish operation (e.g. changing title or extending expires_at) and no get_page to fetch metadata by id. Agents wanting to modify a published page hit a dead end.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Publishes HTML pages straight from your AI assistant to a shareable URL, then lets you manage them - update, list, search, fetch, and delete pages in a public or private workspace. Turns "share what I just made" into a single tool call from Claude, Cursor, or any MCP client.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Publish Markdown or HTML to a shareable link from your AI assistant, then list, inspect, update or delete your pages. Six tools cover publishing, page management and account usage. Connect through hosted Streamable HTTP with OAuth, or use an API key for headless clients.
      6
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to publish HTML or Markdown to a public URL with a single HTTP POST, automatically converting Markdown to a styled webpage, with no account or setup required.
      7 npm
      1
      MIT