🚀 EPHEMO

The instant edge deployment primitive for AI agents and the humans who build with them.

ephemo.online · Master Documentation · Agent Skill

⚡️ What is Ephemo?

Ephemo is an edge-native hosting infrastructure designed specifically for the era of autonomous AI agents. It allows both human developers and AI systems to deploy static web artifacts (HTML, CSS, JS, Media) directly to Cloudflare's global edge network in under 2 seconds, with absolutely zero configuration.

npx ephemo -y ./your-site
# > ✅ LIVE: https://abc123.ephemo.online

Why it exists: AI Agents (like Claude Code, Cursor, OpenClaw) are brilliant at writing code, but struggle with the friction of traditional hosting (Vercel configurations, GitHub integrations, build pipelines). Ephemo removes the friction. It acts as a "Visual Mouth" for agents, allowing them to instantly turn code in a local sandbox into a live, interactive, public URL.

🤖 The Agent-First Workflow

Ephemo was built from the ground up to be operated by machines.

1. Non-Interactive by Default: Append -y to any command, and the CLI will never pause for human input.
2. Machine-Readable: Append --json to receive deterministic, perfectly structured JSON output for your agent's parser.
3. The "Handoff" Protocol: Agents can deploy a site anonymously, grab the outputted Claim Code, and hand it to the human user: "I built this dashboard. Visit this claim link to keep it forever."

Add Ephemo to your Agent (OpenClaw / Hermes)

Install the official skill package to give your agent the ability to deploy sites autonomously:

npx skills add sandrakottos/ephemo-skill --skill ephemo

See the Skill Repository for detailed prompt directives.

📦 Quick Start & CLI Reference

Run Ephemo directly without installation using npx, or install it globally via npm install -g ephemo.

Core Commands

# 1. Deploy a site (Zero Setup)
npx ephemo -y ./your-directory

# 2. Login to claim permanent hosting (Get key from ephemo.online/dashboard.html)
npx ephemo login <YOUR_API_KEY>

# 3. View your active deployments
npx ephemo list

# 4. Promote an anonymous site to your permanent account
npx ephemo claim <slug> <claim_code>

# 5. Overwrite an existing site with new code
npx ephemo update <slug> ./new-dist [claim_code]

# 6. Take a site offline (Soft Delete)
npx ephemo delete <slug> [claim_code]

Advanced Options

# Deploy explicitly anonymously (ignores locally saved credentials)
npx ephemo -y --anon ./your-directory

# Force the browser to open the site immediately after deployment
npx ephemo -y --open ./your-directory

# Check your current authentication status
npx ephemo whoami

🔄 The Two-State Architecture

Ephemo balances zero-friction speed with long-term reliability by using a two-tier lifecycle:

| Tier | Description | | :--- | :--- | | Anonymous | Zero friction. No account required. Deploy instantly. Sites expire in 24 hours. The CLI outputs an 8-character Claim Code. | | Permanent | Full control. Requires a one-time npx ephemo login. Sites never expire. You get a dashboard to manage your fleet of apps. |

The Magic Conversion: To convert an Anonymous site to a Permanent site, the human can visit ephemo.online/dashboard.html and enter the 8-character Claim Code, OR the agent can run npx ephemo claim <slug> <claim_code> directly in the terminal after logging in.

🛡️ Hard Limits & Quotas (Safe Launch)

Ephemo is engineered to prevent abuse while remaining a powerhouse for AI artifacts. We enforce strict limits at both the CLI level and the Cloudflare Edge.

• Payload Size Limits:
  • Anonymous: Maximum 100 MB per upload.
  • Permanent (Auth): Maximum 500 MB per upload. (Note: Artifacts >20MB are automatically routed through an S3-compatible pre-signed URL workflow to bypass edge memory constraints).
• Account Quotas:
  • Authenticated accounts are limited to 500 active sites and 1 GB of total storage.
  • Soft-deleting a site via npx ephemo delete immediately restores that storage to your quota.
• Rate Limits:
  • Deployments: 60 deploys per hour (per IP for Anonymous, per Account for Authenticated).
  • Web Traffic: 100 requests per minute per site.

🔒 Security Best Practices

Ephemo is an open, public architecture designed for front-end code (HTML, CSS, JS, images, videos).

CRITICAL WARNINGS:

1. Never upload backend code (server.js, app.py, .env files). Ephemo will serve these files as plain text, exposing your logic. The CLI includes a "Smart Reject" feature that tries to block backend files, but you are ultimately responsible for your payload.
2. Never embed secret API Keys (OpenAI, Stripe, etc.) into your deployed front-end code. If your static site needs data, have your agent fetch the data locally, save it as a data.json file, and deploy that file alongside the HTML.
3. Your Ephemo API key is securely stored at ~/.ephemo_credentials with chmod 600 permissions. Never commit this file.

ephemo.online · Built for the machines. Designed for the humans.