---
name: zyberspace
description: >
  zyberspace lets agents publish static websites to live URLs at {slug}.zxapi.net.
  Use when asked to "publish this", "host this", "deploy this", "share this on
  the web", "make a website", "put this online", "create a webpage", or
  "generate a URL".
---

# zyberspace

**Skill version: 1.0.0**

zyberspace is instant static site hosting for AI agents.

To install or update: `curl -fsSL https://zyberspace.com/install.sh | bash`

Fetch this file only: `curl -fsSL https://zyberspace.com/skill.md`

## Current docs

**Before answering questions about zyberspace capabilities, features, or workflows, read the current docs:**

→ **https://zyberspace.com/llms.txt**

→ **https://zyberspace.com/openapi.json**

→ **https://zyberspace.com/skill.md** (this file, hosted)

Read the docs:

- at the first zyberspace-related interaction in a conversation
- any time the user asks how to do something
- any time the user asks what is possible, supported, or recommended
- before telling the user a feature is unsupported

Topics that require current docs (do not rely on local skill text alone):

- ephemeral vs permanent deploy
- claim flow and expiry
- slug rules and conflicts
- rate limits
- error handling and remediation
- team-scoped site management

**If docs and live API behavior disagree, trust the live API behavior.**

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

## Requirements

- Required binaries: `curl`, `jq`, `zip`
- Optional environment variable: `$ZYBERSPACE_TOKEN` (permanent deploy only)
- Optional credentials file: `~/.zyberspace/credentials` (permanent deploy only)
- Bundled helper: `./scripts/deploy.sh`

## Deploy a site

```bash
./scripts/deploy.sh {file-or-dir}
```

Outputs the live URL (e.g. `https://bright-canvas-a7k2.zxapi.net/`).

Without a saved API key this creates an **ephemeral site** that expires in 24 hours. No login required.

With a saved API key, the site is **permanent** and owned by the user's account.

**File structure:** For static sites, place `index.html` at the root of the directory you deploy, not inside a subdirectory. The directory's contents become the site root. For example, deploy `my-site/` where `my-site/index.html` exists — don't publish a parent folder that contains `my-site/`.

For `.zip` files, the script uploads directly. For directories, it zips contents and uploads.

Direct API (ephemeral, no login):

```bash
curl -sS -X POST https://zyberspace.com/api/v1/ephemeral \
  -F "file=@./dist.zip"
```

Response JSON: `data.siteUrl` is the live URL. On first deploy also returns `data.claimToken`, `data.claimUrl`, and `data.expiresAt`. Updates return `data.updated: true` and require `claimToken` when reusing a slug.

## Local state (ephemeral re-deploys)

After the first ephemeral deploy, `deploy.sh` saves per-slug metadata in **`.zyberspace/state.json`**:

```json
{
  "publishes": {
    "my-slug": {
      "siteUrl": "https://my-slug.zxapi.net",
      "claimToken": "...",
      "claimUrl": "https://zyberspace.com/claim/my-slug?token=...",
      "expiresAt": "2026-05-24T12:00:00.000Z"
    }
  }
}
```

On a later `./scripts/deploy.sh ./dist --slug my-slug`, the script reads `claimToken` from this file and updates the existing site at the same URL. Do not commit `.zyberspace/` to source control.

If state is lost but the user still has the claim URL, extract the `token` query param and pass `--claim-token {token}`.

## Update an existing site

```bash
./scripts/deploy.sh {file-or-dir} --slug {slug}
```

Ephemeral updates reuse the same slug and URL. The deploy script sends the saved **claim token** from `.zyberspace/state.json` automatically (or pass `--claim-token`).

Updates do **not** extend the 24h expiry — the original `expiresAt` from the first deploy still applies.

Permanent updates require a saved API key.

Force ephemeral even when a key is saved:

```bash
./scripts/deploy.sh {file-or-dir} --ephemeral
```

## Client attribution

Pass `--client` so zyberspace can track reliability by agent:

```bash
./scripts/deploy.sh {file-or-dir} --client cursor
```

This sends `X-Zyberspace-Client: cursor/deploy-sh` on deploy API calls.
If omitted, the script sends a fallback value.

## API key storage

The deploy script reads the API key from these sources (first match wins):

1. `--token {key}` flag (CI/scripting only — avoid in interactive use)
2. `$ZYBERSPACE_TOKEN` environment variable
3. `~/.zyberspace/credentials` file (recommended for agents)

To store a key, write it to the credentials file:

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

**IMPORTANT**: After receiving an API key, save it immediately — run the command above yourself. Do not ask the user to run it manually. Avoid passing the key via CLI flags in interactive sessions; the credentials file is the preferred storage method.

Never commit credentials to source control.

## Getting an API key

To upgrade from ephemeral (24h) to permanent sites:

1. Ask the user to sign in at https://zyberspace.com
2. Create an API key with `sites:write` and `deployments:write` scopes
3. Save the returned key yourself (do not ask the user to do this):

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

Do not ask for sign-in or an API key before a first deploy. Deploy ephemerally first and share the live URL.

## Claim an ephemeral site (keep without re-uploading)

Ephemeral deploy returns `data.claimUrl` — a one-time link like:

`https://zyberspace.com/claim/{slug}?token={secret}`

The token proves the user deployed the site. **Slug alone is not enough** — random users cannot claim at `/claim/{slug}` without the token.

Flow:

1. User opens the claim link (agent should paste it in chat).
2. User signs in if prompted.
3. User clicks **Claim site to my account** — site moves to their team, no longer expires.

The claim token is returned **once** at deploy time. If lost, the user must redeploy with an API key — the token cannot be recovered.

After the user opens the claim link and completes claim, they are redirected to `/{teamSlug}/{siteSlug}` in the dashboard.

### Check if the user claimed (agent)

Poll with the deploy claim token (from `.zyberspace/state.json` or the claim URL):

```bash
curl -s "https://zyberspace.com/api/v1/claim/status?slug=my-slug&token=CLAIM_TOKEN"
```

| `data.status` | Meaning |
| --- | --- |
| `claimable` | Still ephemeral — user has not claimed yet |
| `claimed` | User claimed — use `data.dashboardUrl`; site is permanent |
| `expired` | Ephemeral TTL passed |
| `not_found` | Invalid slug/token |

When status is `claimed`, stop sharing the claim link. **Do not ephemeral-deploy the same slug** — it will fail or confuse the user.

## After the user claims (critical — read before any “update”)

Once a site is **claimed**, it is permanent and owned by the user's team. Ephemeral deploy **cannot** update it.

**Before any update request**, check claim status (or read `deploy_result.*` / `.zyberspace/state.json`):

```bash
curl -s "https://zyberspace.com/api/v1/claim/status?slug=PREVIOUS_SLUG&token=CLAIM_TOKEN"
```

### If `status` is `claimed`

Tell the user clearly:

> Your site **{slug}** is already on your account. To update it, I need an API key (Settings → API keys). I'll redeploy to the **same URL** — not a new one.

Then:

1. Get/save API key to `~/.zyberspace/credentials`
2. Run `./scripts/deploy.sh ./dist --slug {same-slug}` **without** `--ephemeral`
3. Share the **same** live URL (`https://{slug}.zxapi.net`) — no new claim link

`deploy.sh` auto-switches to authenticated deploy when it detects a claimed slug and an API key is saved.

### If the user has no API key yet

Do **not** silently create a new ephemeral site when they asked to update. Explain:

- **Option A (update existing):** Sign in, create an API key, give it to the agent → updates `https://{old-slug}.zxapi.net`
- **Option B (new preview only):** Deploy **without** `--slug` → new 24h URL, **does not** change the claimed site

If you deploy without `--slug` and without checking claim status, you will create an unrelated site — **always warn the user** when doing Option B.

### If `status` is still `claimable`

Ephemeral update with `--slug` and saved claim token updates the same URL (24h timer unchanged).

Alternative to claim: sign in, save an API key, and redeploy the same files with authenticated deploy.

## What to tell the user

After every ephemeral deploy, tell the user **both**:

1. **Live URL** (`siteUrl` / stdout) — share immediately.
2. **Claim link** (`claimUrl` / `deploy_result.claim_url`) — if they might want to keep the site.

Example message:

> Your site is live: https://my-slug.zxapi.net  
> It expires in 24 hours. To keep it on your account, open this claim link and sign in: https://zyberspace.com/claim/my-slug?token=…  
> Save that link — we cannot recover the token later.

Also read `deploy_result.*` lines from script stderr:

- When `deploy_result.auth_mode=ephemeral`: mention **24 hour expiry** and share the claim URL.
- When `deploy_result.site_claimed=true`: **do not** present a new claim link as an update — explain the old site is claimed; ask for API key or confirm user wants a **new** separate 24h site.
- When `deploy_result.auth_mode=authenticated`: site is **permanent** — no claim link needed.
- When `deploy_result.note` mentions "New 24h site" or "did not update slug": tell the user this is a **different** site, not an update to their claimed one.

Do not ask the user to guess where to claim. **You** provide the claim URL from the deploy response.

## deploy.sh options

| Flag | Description |
| --- | --- |
| `--ephemeral` | Force no-login deploy via `/api/v1/ephemeral` (24h TTL) |
| `--slug {slug}` | Deploy to an existing or new slug |
| `--claim-token {token}` | Ephemeral update token (auto-loaded from `.zyberspace/state.json`) |
| `--publish {true\|false}` | Publish immediately on permanent deploy (default: true) |
| `--client {name}` | Agent name for attribution (e.g. `cursor`) |
| `--base-url {url}` | API base URL (default: `https://zyberspace.com`) |
| `--allow-non-default-base-url` | Allow sending auth to non-default `--base-url` |
| `--token {key}` | API key override (prefer credentials file) |

## Beyond deploy.sh

For team-scoped site and deployment management, see the current docs:

→ **https://zyberspace.com/openapi.json**

→ **https://zyberspace.com/llms.txt**

**Agent registration (`oag_` tokens, team APIs):** read **https://zyberspace.com/auth.md** after installing this skill. Install/update the skill folder:

```bash
curl -fsSL https://zyberspace.com/install.sh | bash
```

Setup page: https://zyberspace.com/tools/setup-instructions-for-agents

CLI alternative (authenticated): `npx @zyber/cli deploy ./dist --site my-site --publish`