Mist Domain

Concepts

URL schema

# Web UI
/{owner}/mists/{mist_id}           # detail page
/{owner}/mists/{mist_id}/embed     # iframe-safe embed card
/{owner}/mists/{mist_id}/raw       # raw artifact download
/{owner}/mists                     # owner's public mist list
/mists/explore                     # global discovery feed

# REST API
POST   /api/mists                  # create
GET    /api/mists/{mist_id}        # read
PATCH  /api/mists/{mist_id}        # update (owner only)
DELETE /api/mists/{mist_id}        # delete (owner only)
POST   /api/mists/{mist_id}/fork   # fork
GET    /api/mists/{mist_id}/forks  # list direct forks
GET    /api/mists/explore          # global public feed
GET    /api/{owner}/mists          # owner's public list

# MCP Resource
musehub://mists/{owner}/{mist_id}  # single mist resource
musehub://mists/{owner}            # owner's mist list resource

Artifact types

The server auto-detects the artifact type from the filename and content bytes. Callers may omit artifact_type in POST /api/mists — the server fills it in. Symbol anchors are extracted automatically for Python, JavaScript, and TypeScript code artifacts.

CLI reference

The muse mist subcommand is the primary interface for humans and agents.

Create

muse mist create <file> [options]

  --title TEXT          Human-readable title
  --description TEXT    Longer description (shown on the detail page)
  --visibility          public (default) | secret
  --tags TAG,...        Comma-separated tags (max 10, 64 chars each)
  --agent-id TEXT       Agent identifier for provenance
  --model-id TEXT       Model ID for agent provenance
  --sign                Sign with the local Ed25519 identity key
  --push                Push to the configured hub after creation
  --json                Machine-readable output

muse mist create validate_handle.py \
  --title "Handle validation primitive" \
  --tags "security,auth" \
  --sign --push --json
# → {"mist_id": "aB3xKq9dPwNm", "url": "http://staging.musehub.ai/gabriel/mists/aB3xKq9dPwNm", ...}

Other commands

REST API

All write endpoints require Authorization: MSign ... (see Cryptographic Identity).

POST /api/mists

Create a new mist. The mist_id is computed by the server.

{
  "filename":    "validate_handle.py",
  "content":     "def _validate_handle(h): ...",
  "visibility":  "public",
  "title":       "Handle validation primitive",
  "description": "Security gate used by auth middleware.",
  "tags":        ["security", "auth"],
  "agentId":     "cccode-v3",
  "modelId":     "claude-sonnet-4-6"
}

Returns 201 with the full mist object. Returns 409 if the same content already exists under your handle (idempotent — the existing mist_id is stable).

GET /api/mists/explore

Global public discovery feed. Supports artifact_type and cursor pagination.

GET /api/mists/explore?artifact_type=code&limit=20&cursor=<ISO-8601>

{
  "mists":      [...],
  "total":      1234,
  "nextCursor": "2026-04-14T09:30:00+00:00"
}

PATCH /api/mists/{mist_id}

Partial update. Only provided fields change. Updating content increments version and records a new commit on the backing repo. Returns 404 if not found or caller is not the owner.

DELETE /api/mists/{mist_id}

Hard delete. Returns 204 on success, 404 if not found or not the owner.

POST /api/mists/{mist_id}/fork

Create a fork. Returns 422 if the parent is already at fork depth 5.

MCP tools & resources

Resources:

musehub://mists/{owner}/{mist_id}   — full mist response (content included)
musehub://mists/{owner}             — owner's public mist list (no content)

Secret mists are returned for the authenticated owner; unauthenticated or non-owner reads return a forbidden error.

Agent publishing workflow

An agent session produces an artifact it wants to share permanently:

# Via MCP tool (no shell required):
result = muse_mist_create(
    filename="validate_handle.py",
    content=content,
    title="Handle validation security primitive",
    agent_id="cccode-v3",
    model_id="claude-sonnet-4-6",
    visibility="public",
    tags=["security", "auth"],
)
# → {"mistId": "aB3xKq9dPwNm", "url": "http://staging.musehub.ai/gabriel/mists/aB3xKq9dPwNm", ...}

# Or via CLI (signed with MUSE_AGENT_KEY env var injected by Agentception):
muse mist create /tmp/validate_handle.py \
  --title "Handle validation security primitive" \
  --agent-id cccode-v3 \
  --model-id claude-sonnet-4-6 \
  --sign --push --json

The resulting URL is a permanent, verifiable artifact. The agent_id and model_id fields prove provenance. In the ERC-8004 on-chain identity world: agent contract address → MSign key → Mist signature → content hash.

Forking & sub-domain delegation

Every Mist is a Muse repo (domain="mist"). Forking creates a new repo whose first commit copies the parent's content. The fork graph is visible on the detail page sidebar (Forked From + Forks panels).

Sub-domain delegation (future): Because each Mist backs a full Muse repo, any future domain plugin (genomics, spatial, MIDI v2) can be applied to the backing repo, gaining symbol-level diffs, blast radius, and AST versioning for free.

Embedding

iframe

<iframe
  src="http://staging.musehub.ai/{owner}/mists/{mist_id}/embed"
  width="600"
  height="400"
  frameborder="0"
  title="my_file.py">
</iframe>

Script tag

<script
  src="http://staging.musehub.ai/embed.js"
  data-mist="{owner}/{mist_id}">
</script>

The embed card shows the artifact type chip, filename, syntax-highlighted content, size/version metadata, and a "View on MuseHub" link. The embed endpoint increments embed_count on each render. Cross-origin framing is allowed (frame-ancestors *).

Content addressing

The mist_id is computed deterministically from the artifact bytes:

import hashlib, base58

def compute_mist_id(content: bytes) -> str:
    digest = hashlib.sha256(content).digest()
    return base58.b58encode(digest).decode()[:12]

Security model

Limits