here.now: Website Publishing and Cloud Drive Reference

This document describes how agents can publish websites and manage private cloud storage using the here.now platform. The system provides two core capabilities: publishing directories or files as live websites at a {slug}.here.now URL, and storing private files in cloud Drives for agent use.

Prerequisites

Before using the here.now tools, ensure the following are in place:

Required binaries: curl, file, jq
Skill helper scripts must exist at ${HERMES_SKILL_DIR}/scripts/publish.sh and ${HERMES_SKILL_DIR}/scripts/drive.sh
Optional environment variables: $HERENOW_API_KEY and $HERENOW_DRIVE_TOKEN
Optional credentials file: ~/.herenow/credentials
For authenticated operations: a valid API key stored in the credentials file or environment variable
For Drive operations: a valid Drive token or signed-in account with a default Drive

Publishing Websites

The publish script handles the complete workflow of creating, uploading, and finalizing a site. The site is not live until the finalize step succeeds.

Create a Site

To publish a file or directory as a new site:

PUBLISH="${HERMES_SKILL_DIR}/scripts/publish.sh"
bash "$PUBLISH" {file-or-dir} --client hermes

The script performs a three-step flow: create or update, upload files, and finalize. Without a saved API key, the site is anonymous and expires in 24 hours. With a saved API key, the site is permanent. The output is the live URL, for example https://bright-canvas-a7k2.here.now/.

Update an Existing Site

To update a previously published site, provide the slug:

PUBLISH="${HERMES_SKILL_DIR}/scripts/publish.sh"
bash "$PUBLISH" {file-or-dir} --slug {slug} --client hermes

The script automatically loads the claimToken from .herenow/state.json for anonymous updates. To override the auto-loaded token, pass --claim-token {token}. Authenticated updates require a saved API key.

Publishing Parameters

The following parameters can be used with the publish script:

--slug {slug}: Update an existing site instead of creating a new one
--claim-token {token}: Override the claim token for anonymous updates
--title {text}: Viewer title for non-HTML sites
--description {text}: Viewer description for non-HTML sites
--ttl {seconds}: Set expiry for authenticated sites only
--client {name}: Agent name for attribution (e.g., hermes)
--base-url {url}: API base URL (default: https://here.now)
--allow-nonherenow-base-url: Allow sending auth to a non-default --base-url
--api-key {key}: API key override (prefer the credentials file)
--spa: Enable SPA routing (serve index.html for unknown paths)
--forkable: Allow others to fork this site

Site Structure

For HTML sites, place index.html at the root of the published directory, not inside a subdirectory. For example, use my-site/index.html rather than my-site/subdir/index.html.

Anonymous Site Expiry and Claim Tokens

Anonymous sites expire in 24 hours. Claim tokens are returned only once and cannot be recovered. If an anonymous site is not claimed within 24 hours, it expires and is lost. The state file .herenow/state.json stores claim information but should never be presented as a URL or used as a source of truth for auth mode, expiry, or claim URL.

Cloud Drives

Drives provide private cloud storage for documents, context, memory, plans, assets, media, research, code, or any other persistent files that should not be publicly published.

Using the Drive Script

The drive script provides a convenient interface for common operations:

DRIVE="${HERMES_SKILL_DIR}/scripts/drive.sh"
bash "$DRIVE" default
bash "$DRIVE" ls "My Drive"
bash "$DRIVE" put "My Drive" notes/today.md --from ./notes/today.md
bash "$DRIVE" cat "My Drive" notes/today.md
bash "$DRIVE" share "My Drive" --perms write --prefix notes/ --ttl 7d

The commands perform the following actions:

bash "$DRIVE" default: List the default Drive
bash "$DRIVE" ls "My Drive": List contents of the specified Drive
bash "$DRIVE" put "My Drive" notes/today.md --from ./notes/today.md: Upload a file to the Drive
bash "$DRIVE" cat "My Drive" notes/today.md: Read a file from the Drive
bash "$DRIVE" share "My Drive" --perms write --prefix notes/ --ttl 7d: Share a folder with a scoped token

Drive Sharing and Scoped Tokens

When sharing Drive access with another agent, prefer a scoped token with a narrow pathPrefix and short TTL. For a received herenow_drive share block:

Use the token as Authorization: Bearer against api_base
Respect pathPrefix when present; a pathPrefix of null means full-Drive access
Preserve ETags on writes

Prefer drive.sh if available; otherwise call the Drive API directly. Drive contents are private unless shared with a scoped token. Do not describe Drive files as public URLs.

Authentication and API Keys

Get an API Key (Upgrade from Anonymous to Permanent)

To upgrade an anonymous site to a permanent one, obtain an API key:

Ask the user for their email address.
Request a one-time sign-in code:

curl -sS https://here.now/api/auth/agent/request-code \
  -H "content-type: application/json" \
  -d '{"email": "user@example.com"}'

Tell the user: "Check your inbox for a sign-in code from here.now and paste it here."
Verify the code and get the API key:

curl -sS https://here.now/api/auth/agent/verify-code \
  -H "content-type: application/json" \
  -d '{"email":"user@example.com","code":"ABCD-2345"}'

Save the returned apiKey yourself:

mkdir -p ~/.herenow && echo "{API_KEY}" > ~/.herenow/credentials && chmod 600 ~/.herenow/credentials

Store an API Key

Write the key to the credentials file immediately after receiving it. Do not ask the user to run this command; execute it yourself:

mkdir -p ~/.herenow && echo "{API_KEY}" > ~/.herenow/credentials && chmod 600 ~/.herenow/credentials

Avoid passing the API key via --api-key {key} in interactive sessions; prefer the credentials file. Never commit ~/.herenow/credentials or .herenow/state.json to source control.

State File

The state file .herenow/state.json stores information about published sites. An example structure:

{
  "publishes": {
    "bright-canvas-a7k2": {
      "siteUrl": "https://bright-canvas-a7k2.here.now/",
      "claimToken": "abc123",
      "claimUrl": "https://here.now/claim?slug=bright-canvas-a7k2&token=abc123",
      "expiresAt": "2026-02-18T01:00:00.000Z"
    }
  }
}

The fields include siteUrl, claimToken, claimUrl, and expiresAt. The publish_result.* fields such as publish_result.auth_mode=authenticated, publish_result.auth_mode=anonymous, and publish_result.claim_url may also be relevant. Never present .herenow/state.json as a URL or use it as a source of truth for auth mode, expiry, or claim URL.

Failure Modes

Docs fetch fails or times out: continue with local skill and live API or script output
Live API behavior disagrees with docs: trust live API behavior
Missing required binaries (curl, file, jq): script will fail
Anonymous site not claimed within 24 hours: site expires and is lost
Claim token lost: cannot recover; site cannot be made permanent
API key not saved: subsequent authenticated operations fail
Drive token invalid or expired: Drive operations fail
File structure incorrect (e.g., index.html in subdirectory): site may not render as expected
State file .herenow/state.json corrupted or missing: update may fail for anonymous sites (claimToken not found)

Additional Capabilities

The here.now platform supports additional features that require consulting the current documentation at https://here.now/docs. Read the docs at the first here.now interaction, when the user asks how to do something, when the user asks what is possible or supported, and before telling the user a feature is unsupported. Topics requiring current docs include:

Drives and Drive sharing
Custom domains
Payments and payment gating
Forking
Proxy routes and service variables
Handles and links
Limits and quotas
SPA routing
Error handling and remediation
Feature availability

If the docs fetch fails or times out, continue with local skill and live API or script output, preferring live API behavior for active operations.

Publishing Sites and Using Drives with the here.now Skill in Hermes Agent