ZenBin

A headless HTML sandbox — publish and serve HTML documents via a simple API.

Overview

ZenBin is a lightweight web service that lets you publish HTML documents to unique IDs and view them at predictable URLs. It's optimized for fast sharing, demos, prototypes, and lightweight hosting of single-page HTML documents.

Features

Simple API — Store HTML by ID with a single POST request
Markdown support — Store markdown source alongside HTML, retrieve via /md endpoint or content negotiation
Image support — Upload images up to 5MB (PNG, JPEG, GIF, WebP, SVG)
Instant rendering — View pages at /p/{id} in any browser
Raw access — Fetch original HTML at /p/{id}/raw
Markdown endpoint — Fetch markdown source at /p/{id}/md
Image endpoint — Fetch images directly at /p/{id}/image
Proxy endpoint — Make external API calls from hosted pages (CORS bypass)
Safe by default — Sandboxed rendering with restrictive security headers
ETag caching — Efficient caching with If-None-Match support
Rate limiting — Built-in abuse protection
Fast storage — LMDB for high-performance reads/writes
Page authentication — Optional password protection or secret URL tokens

Quick Start

# Install dependencies
npm install
# Run in development mode
npm run dev
# Or build and run in production
npm run build
npm start

The server starts at http://localhost:3000 by default.

API Reference

Create or Replace a Page

POST /v1/pages/{id}
Content-Type: application/json

Request body:

{
"html": "<!doctype html><html><body>Hello World</body></html>",
"markdown": "# Hello World\n\nThis is the markdown source.",
"image": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
"title": "My Page",
"encoding": "utf-8",
"markdown_encoding": "utf-8",
"content_type": "text/html; charset=utf-8"
}

Field	Required	Description
`html`	No*	HTML content (string). *At least one of `html`, `markdown`, or `image` is required.
`markdown`	No*	Markdown source content (string). *At least one of `html`, `markdown`, or `image` is required.
`image`	No*	Base64-encoded image data. *At least one of `html`, `markdown`, or `image` is required.
`title`	No	Page title (metadata)
`encoding`	No	`utf-8` (default) or `base64` for the `html` field
`markdown_encoding`	No	`utf-8` (default) or `base64` for the `markdown` field
`content_type`	No	Content-Type header (default: `text/html; charset=utf-8`). Required for image pages.
`auth`	No	Authentication settings (see Page Authentication)

Response:

{
"id": "my-page",
"url": "http://localhost:3000/p/my-page",
"raw_url": "http://localhost:3000/p/my-page/raw",
"markdown_url": "http://localhost:3000/p/my-page/md",
"etag": "\"abc123...\""
}

Returns 201 Created for new pages
Returns 200 OK when updating existing pages
markdown_url is only included when markdown is provided

Updating Pages

Subdomain pages: Just POST again with the same ID and X-Subdomain header. No special flag needed.

Non-subdomain pages: Add ?overwrite=true query parameter:

POST /v1/pages/my-page?overwrite=true

Password-protected pages: Include Basic Auth header when updating:

curl -X POST http://localhost:3000/v1/pages/secret?overwrite=true \
-H "Content-Type: application/json" \
-u ":mypassword123" \
-d '{"html": "<h1>Updated</h1>"}'

Delete a Page

DELETE /v1/pages/{id}

For password-protected pages, include Basic Auth. For subdomain pages, include X-Subdomain header.

View a Page

GET /p/{id}

Returns the HTML page with security headers applied. Supports If-None-Match for caching (returns 304 Not Modified if unchanged).

Fetch Raw HTML

GET /p/{id}/raw

Returns the raw HTML as text/plain with a Content-Disposition header for downloading.

Fetch Markdown Source

GET /p/{id}/md

Returns the markdown source as text/markdown. Returns 404 if the page has no markdown content.

Alternatively, request markdown via content negotiation:

GET /p/{id}
Accept: text/markdown

Markdown-Only Pages

If a page is created with only markdown (no HTML), GET /p/{id} automatically returns the markdown content with Content-Type: text/markdown.

Images

Upload images up to 5MB. Supported formats: PNG, JPEG, GIF, WebP, SVG.

Create an image page:

# Encode image to base64
IMAGE_BASE64=$(base64 -i myimage.png | tr -d '\n')
curl -X POST http://localhost:3000/v1/pages/my-logo \
-H "Content-Type: application/json" \
-d "{\"image\": \"$IMAGE_BASE64\",\"content_type\": \"image/png\" }"

Access the image:

# View in browser
GET /p/my-logo
# Explicit image endpoint
GET /p/my-logo/image

The image is served with the correct Content-Type header. When a page has both html and image, the HTML is served at /p/{id} and the image at /p/{id}/image.

Health Check

GET /health

Returns {"status": "ok", "timestamp": "..."}.

Agent Instructions

GET /api/agent

Returns markdown instructions for AI agents on how to use the API.

Proxy External Requests

POST /api/proxy
Content-Type: application/json

Allows ZenBin-hosted pages to make external HTTP requests through the server, bypassing CORS restrictions.

Request body:

{
"url": "https://api.example.com/data",
"method": "GET",
"auth": {
"type": "bearer",
"credentials": "your-token"
}
}

Field	Required	Description
`url`	Yes	Target URL (http/https only)
`method`	No	HTTP method (default: `GET`)
`body`	No	Request body to forward (JSON)
`timeout`	No	Timeout in ms (max: 30000)
`contentType`	No	Content-Type for outgoing request
`accept`	No	Accept header for outgoing request
`auth`	No	Authentication config (see below)

Authentication types:

Type	Usage	Result Header
`bearer`	`{ type: "bearer", credentials: "token" }`	`Authorization: Bearer token`
`basic`	`{ type: "basic", credentials: "base64" }`	`Authorization: Basic base64`
`api-key`	`{ type: "api-key", credentials: "key", headerName: "X-API-Key" }`	`X-API-Key: key`

Response:

{
"status": 200,
"statusText": "OK",
"headers": { "content-type": "application/json" },
"body": { ... }
}

Security: Only requests originating from ZenBin-hosted pages are allowed. SSRF protection blocks private IPs and internal endpoints.

Examples

Simple page

curl -X POST http://localhost:3000/v1/pages/hello \
-H "Content-Type: application/json" \
-d '{"html":"<h1>Hello World</h1>"}'

Styled page

curl -X POST http://localhost:3000/v1/pages/demo \
-H "Content-Type: application/json" \
-d '{ "html": "<!DOCTYPE html><html><head><style>body{font-family:sans-serif;padding:2rem}</style></head><body><h1>Demo</h1><p>This is a demo page.</p></body></html>", "title": "Demo Page" }'

Base64 encoded content

# Encode your HTML
HTML_BASE64=$(echo -n '<h1>Encoded</h1>'| base64)
curl -X POST http://localhost:3000/v1/pages/encoded \
-H "Content-Type: application/json" \
-d "{\"encoding\":\"base64\",\"html\":\"$HTML_BASE64\"}"

Page with HTML and Markdown

curl -X POST http://localhost:3000/v1/pages/article \
-H "Content-Type: application/json" \
-d '{ "html": "<!DOCTYPE html><html><head><style>body{font-family:system-ui;max-width:700px;margin:0 auto;padding:2rem}</style></head><body><h1>My Article</h1><p>Content here.</p></body></html>", "markdown": "# My Article\n\nContent here.", "title": "My Article" }'

Response includes markdown URL:

{
"id": "article",
"url": "http://localhost:3000/p/article",
"raw_url": "http://localhost:3000/p/article/raw",
"markdown_url": "http://localhost:3000/p/article/md",
"etag": "\"...\""
}

Markdown-only page

curl -X POST http://localhost:3000/v1/pages/notes \
-H "Content-Type: application/json" \
-d '{ "markdown": "# Notes\n\n- Item 1\n- Item 2\n- Item 3" }'

Page Authentication

Pages are public by default. You can optionally protect pages with password authentication, secret URL tokens, or both.

Password Protection

Add HTTP Basic Auth to require a password when viewing the page:

curl -X POST http://localhost:3000/v1/pages/secret \
-H "Content-Type: application/json" \
-d '{ "html": "<h1>Secret Page</h1>", "auth": { "password": "mypassword123" } }'

Browsers will automatically prompt for the password. With curl:

curl -u ":mypassword123" http://localhost:3000/p/secret

URL Token (Secret Links)

Generate a secret shareable URL that grants access without a password:

curl -X POST http://localhost:3000/v1/pages/shared \
-H "Content-Type: application/json" \
-d '{ "html": "<h1>Shared Page</h1>", "auth": { "urlToken": true } }'

Response includes secret URLs:

{
"id": "shared",
"url": "http://localhost:3000/p/shared",
"secret_url": "http://localhost:3000/p/shared?token=abc123...",
"secret_raw_url": "http://localhost:3000/p/shared/raw?token=abc123..."
}

If the page has markdown, the response also includes secret_markdown_url:

{
"secret_markdown_url": "http://localhost:3000/p/shared/md?token=abc123..."
}

Note: The token is only returned once at creation and cannot be retrieved later.

Both Methods

Use both password and URL token for maximum flexibility:

curl -X POST http://localhost:3000/v1/pages/dual \
-H "Content-Type: application/json" \
-d '{ "html": "<h1>Dual Auth</h1>", "auth": { "password": "mypassword123", "urlToken": true } }'

Brute-Force Protection

Protected pages have built-in brute-force protection:

After 5 failed attempts within 15 minutes, the page is locked for 15 minutes
Returns 429 Too Many Requests with a Retry-After header when locked

Configuration

Configure via environment variables or .env file:

Variable	Default	Description
`PORT`	`3000`	Server port
`HOST`	`0.0.0.0`	Server host
`BASE_URL`	`http://localhost:3000`	Base URL for generated links
`LMDB_PATH`	`./data/zenbin.lmdb`	Database path
`MAX_PAYLOAD_SIZE`	`524288`	Max HTML/markdown size in bytes (512KB)
`MAX_IMAGE_SIZE`	`5242880`	Max image size in bytes (5MB)
`MAX_ID_LENGTH`	`128`	Max page ID length
`RATE_LIMIT_WINDOW_MS`	`60000`	Rate limit window (ms)
`RATE_LIMIT_MAX_REQUESTS`	`100`	Max requests per window
`PROXY_TIMEOUT_MS`	`30000`	Max timeout for proxy requests
`PROXY_MAX_REQUEST_SIZE`	`5242880`	Max proxy request body (5MB)
`PROXY_MAX_RESPONSE_SIZE`	`5242880`	Max proxy response size (5MB)
`PROXY_ALLOWED_DOMAINS`	``	Comma-separated domain allowlist (empty = all)
`PROXY_RATE_LIMIT_MAX`	`5`	Max proxy requests per window
`PROXY_RATE_LIMIT_WINDOW_MS`	`60000`	Proxy rate limit window (ms)
`PROXY_MAX_REDIRECTS`	`3`	Max redirects to follow
`AUTH_BCRYPT_ROUNDS`	`10`	bcrypt cost factor for password hashing
`AUTH_TOKEN_LENGTH`	`32`	URL token length in bytes (64 hex chars)
`AUTH_MIN_PASSWORD_LENGTH`	`8`	Minimum password length
`AUTH_MAX_FAILED_ATTEMPTS`	`5`	Max failed auth attempts before lockout
`AUTH_FAILED_ATTEMPT_WINDOW_MS`	`900000`	Failed attempt tracking window (15 min)
`AUTH_LOCKOUT_DURATION_MS`	`900000`	Lockout duration after max failures (15 min)
`FREE_TIER_MONTHLY_LIMIT`	`100`	Free tier request limit per 30 days
`FREE_TIER_WINDOW_MS`	`2592000000`	Free tier window in ms (30 days)
`SUBDOMAINS_ENABLED`	`true`	Enable subdomain feature
`SUBDOMAIN_MAX_LENGTH`	`63`	Max subdomain name length
`SUBDOMAIN_MAX_PAGES`	`100`	Max pages per subdomain
`SUBDOMAIN_RESERVED_NAMES`	(see config)	Comma-separated reserved names
`SUBDOMAIN_BASE_DOMAIN`	`zenbin.org`	Base domain for subdomains

Page ID Rules

Page IDs must:

Contain only letters, numbers, dots, underscores, and hyphens (A-Za-z0-9._-)
Be 128 characters or less (configurable)

Valid examples: my-page, demo.v2, user_123, Report-2024.01

Security

Pages are served with restrictive security headers:

Content-Security-Policy — Restricts external resources
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy: same-site
X-Frame-Options: DENY

Deploy to Render

ZenBin includes a render.yaml Blueprint for easy deployment to Render.com.

One-Click Deploy

Manual Setup

Fork or clone this repository
Create a new Blueprint in Render Dashboard
Connect your repository
Set the BASE_URL environment variable to your Render URL (e.g., https://zenbin.org)
Deploy

What's Included

The Blueprint configures:

Web Service — Node.js runtime on the Starter plan
Persistent Disk — 1GB mounted at /var/data for LMDB storage
Health Check — Monitors /health endpoint
Environment Variables — Pre-configured for production

Limitations

Due to Render's persistent disk constraints:

Single instance only — Services with attached disks cannot scale horizontally
No zero-downtime deploys — Brief downtime during redeploys (a few seconds)

For multi-instance deployments, consider replacing LMDB with Render Postgres or Redis.

Development

# Run with hot reload
npm run dev
# Run tests
npm test# Build for production
npm run build

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 55 Commits
.openclaw		.openclaw
blog		blog
posts		posts
public		public
src		src
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
BOOTSTRAP.md		BOOTSTRAP.md
COMPETITIVE_ANALYSIS.md		COMPETITIVE_ANALYSIS.md
HEARTBEAT.md		HEARTBEAT.md
IDENTITY.md		IDENTITY.md
LANDING_PAGE_DESIGN.md		LANDING_PAGE_DESIGN.md
PRD.md		PRD.md
PRODUCT_PLAN.md		PRODUCT_PLAN.md
README.md		README.md
SOUL.md		SOUL.md
STRATEGY.md		STRATEGY.md
TASKS.md		TASKS.md
TOOLS.md		TOOLS.md
USER.md		USER.md
bun.lock		bun.lock
hive-observer-plan-content.html		hive-observer-plan-content.html
launch-thread.md		launch-thread.md
package-lock.json		package-lock.json
package.json		package.json
render.yaml		render.yaml
scout-live-plan-content.html		scout-live-plan-content.html
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
zenbin-designe.pen		zenbin-designe.pen
zenbin-landing-design-1.html		zenbin-landing-design-1.html
zenbin-landing-design-2.html		zenbin-landing-design-2.html

Uh oh!

Folders and files

Latest commit

History

Repository files navigation