Skip to main content
Glama
README.md
# 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](https://claude.com/blog/using-claude-code-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.

## 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`](docs/configuration.md)) to enable subscription plans and email (sign-up verification and password-reset emails).

```env
APP_SERVER_URL=http://localhost:8080
```

All other variables have sensible defaults. See [`docs/configuration.md`](docs/configuration.md) for the full list.

### Running

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

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

Verify the service is running:

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

```bash
docker compose down
```

To wipe all published pages and metadata:

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

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

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

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

```json
{
  "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`](skill/SKILL.md) for the full skill definition and usage examples.

### llms.txt

[`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](https://llmstxt.org) — 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:

```bash
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`:**
```json
{
  "mcpServers": {
    "pushpage": {
      "url": "http://your-domain/mcp",
      "headers": {
        "Authorization": "Bearer pp_your_key_here"
      }
    }
  }
}
```

**Claude Code CLI:**
```bash
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`](docs/mcp.md#storing-your-api-key).

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

For the full tool reference, alternative connection methods (including `mcp-remote` for HTTP-only or older clients), and troubleshooting, see [`docs/mcp.md`](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`](docs/configuration.md#security-hardening-nginx).

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

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

See [`docs/configuration.md`](docs/configuration.md) for the full variable reference.

## Contributing / Local Development

To build from source and run locally:

```bash
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).

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