Docs.

Ephemo is an agent-first edge hosting platform for static artifacts. Zero configuration. Runs on Cloudflare's global edge network. Designed to be driven by autonomous agents or human developers with equal fluency.

1. Start Here

The fastest way to understand Ephemo is to deploy a site right now. Here is the canonical "Happy Path" from a completely anonymous terminal to a permanently hosted website.

1. Deploy Anonymously

You don't need an account. Just run the deploy command in any directory containing an index.html.

# The CLI will prompt you for confirmation. Press Y.
$ npx ephemo ./

You will instantly receive a live URL and an 8-character Claim Code.

2. Make It Permanent

Anonymous sites are deleted after 24 hours. To keep it forever, log in to the Dashboard using your email. Enter your Claim Code in the dashboard to permanently bind the site to your account.

3. Get Your API Key

Once logged in, the dashboard displays your permanent API Key. You can use this to bypass the anonymous flow entirely.

# Save the key to your machine (~/.ephemo_credentials)
$ npx ephemo login sk_live_...

4. Manage Your Fleet

With your API Key saved, you can list, update, or delete your sites programmatically.

# Check your active sites
$ npx ephemo list

# Overwrite the site with new files
$ npx ephemo update <slug> ./dist

2. Workflow & Lifecycle

Ephemo is built on a "Handoff" philosophy. Whether you are a human or an agent, the lifecycle of a site follows a predictable state transition model.

Decision Table

If you are new: npx ephemo ./dir -> Returns a Claim Code.

If you want to save it: npx ephemo claim <slug> <claim_code> -> Site becomes permanent.

If you have an account: npx ephemo login <key> -> All future deploys are permanent.

State Transition Model

Current State	Action	Next State	Expiry Change
None	`publish` (Anonymous)	Anonymous	Set to +24 hours
Anonymous	`update` (with code)	Anonymous	Resets to +24 hours
Anonymous	`claim` (with code)	Permanent	Purged (Never expires)
Permanent	`delete`	Inactive	Purged (Offline)

Handoff Protocol

When an agent deploys anonymously, it receives a claim_url. The agent should present this URL to the human user. The user can then click the link to "Claim" the site into their own dashboard, transitioning the agent's work into a permanent asset.

3. State Model

Every deployment exists in one of two states. The state is determined entirely by whether an API Key was present at the time of deployment.

ANONYMOUS

No account required. The site expires and is purged automatically after 24 hours. The CLI returns a Claim Code valid for exactly 24 hours to transition the site to Permanent status.

PERMANENT

Requires an API Key. Sites never expire. You retain full programmatic control to update, delete, or unpublish at any time. Claimed anonymous sites transition to this state.

3. Good Fit / Bad Fit

Ephemo is highly optimized for specific workloads. Understanding these boundaries will save you from trying to force the wrong architecture onto the platform.

✅ GOOD FIT

Static Landing Pages
Documentation Sites
Personal Portfolios
Agent-Generated Dashboards
UI Mockups & Prototypes
Client-side React/Vue/Svelte apps

❌ BAD FIT

Node.js / Express APIs
Server-Side Rendered (SSR) apps
Databases (Postgres, SQLite)
Apps requiring dynamic server auth
Background workers / Cron jobs

4. CLI Reference

All commands use npx ephemo for zero-install execution.

Deploy

# Deploy the current directory
$ npx ephemo ./

# Deploy silently (no prompts, required for agents)
$ npx ephemo -y ./dist

# Force an anonymous deployment (ignores local credentials)
$ npx ephemo -y --anon ./dist

Authenticate

The CLI uses ~/.ephemo_credentials to store your API key locally. Alternatively, set the EPHEMO_API_KEY environment variable to override local files.

# Save API Key to ~/.ephemo_credentials
$ npx ephemo login sk_live_...

# Check who is currently logged in
$ npx ephemo whoami

# Remove saved credentials completely from this machine
$ npx ephemo logout

Manage

# List all permanent sites on your account
$ npx ephemo list

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

# Overwrite an existing deployment
$ npx ephemo update <slug> ./dist [claim_code]

# Delete a site permanently
$ npx ephemo delete <slug> [claim_code]

Flags

Flag	Description
--json	Output strictly machine-readable JSON. Schema: `success, url, slug, is_permanent, claim_code, claim_url, expires_at`. Unused fields are explicitly `null`.
-y / --silent	Skip all interactive confirmation prompts. Required for agent pipelines.
--open / -o	Open the deployed URL in the browser immediately.
--anon	Force an anonymous deployment even if local credentials exist. Returns a Claim Code.

5. Agent Checklist

If you are an autonomous agent (like Claude or Hermes) building a workflow on Ephemo, you MUST adhere to this operational contract to avoid stalling or failing.

Always use --json: This ensures all output is machine-readable and predictable. Never try to parse the human-readable text output.
Always use -y or --silent: This skips interactive terminal prompts. If you forget this, your process will hang indefinitely waiting for user input.
Check whoami: Before deploying, run npx ephemo whoami --json. If persistent state matters, know whether you are deploying anonymously or to a permanent account.
Use --anon for isolation: If you explicitly want a Claim Code to hand back to the user, pass --anon to force an anonymous deployment, bypassing any saved credentials.
Clean up: Use npx ephemo logout when switching contexts or to ensure no residual API keys are left in the local filesystem.

6. Failure Cases

Ephemo uses standard HTTP status codes and structured JSON errors. Here is what to expect when things go wrong.

# Error: Deploying a directory without an index.html
# Result: HTTP 400. Ephemo requires an entry point.
{ "error": "Missing index.html in the root directory" }

# Error: Updating an anonymous site without the Claim Code
# Result: HTTP 401. Anonymous sites require the claim_code to overwrite.
{ "error": "claim_code required to overwrite anonymous site" }

# Error: Trying to claim a site after 24 hours
# Result: HTTP 404. The site and claim code have been purged.
{ "error": "Invalid or expired claim code" }

# Error: Uploading a file larger than limits
# Result: HTTP 413. Payload Too Large. Rejected at pre-flight.
{ "error": "Payload exceeds maximum allowed size" }

# Error: Exceeding account quotas
# Result: HTTP 403. Account limit reached.
{ "error": "Account limit reached: Maximum 500 sites allowed." }

7. Technical Notes

For advanced integration and understanding edge architecture.

Payload Routing & Limits

Deployments under 20MB are buffered in edge memory for instant response. Artifacts up to the limit automatically switch to a multipart streaming workflow — the CLI uploads directly to Cloudflare R2 via pre-signed S3 URLs, bypassing edge memory limits entirely.

Anonymous: Max 100MB per payload.
Permanent (Authenticated): Max 500MB per payload.

Security & Storage

Quotas: Permanent accounts are limited to a total of 1GB of storage and a maximum of 500 sites to prevent abuse. Anonymous deployments are unmanaged and purged after 24 hours.
Hashing: Claim Codes and API Keys are stored as SHA-256 hashes. The plaintext secret is returned exactly once at generation time.
Sanitization: Incoming file names are scrubbed server-side to prevent path traversal attacks (zip-slip).
Visibility: Ephemo is public infrastructure. Never deploy .env files, private keys, or sensitive backend code. All deployed assets (HTML, CSS, JS, Images, Videos, PDFs, Fonts) are publicly readable.

Rate Limits

Deployments are capped at 60/hour per IP (Anonymous) or 60/hour per Account (Permanent). Site visitors are limited to 100 requests/minute per IP, returning a 429 Too Many Requests if exceeded.