px — PX protocol

PX is a protocol that makes narrative resources addressable, resolvable, and interoperable across tools, storage systems, formats, and AI workflows.

Characters, locations, scenes, props, and entire fictional repositories — PX gives each one a stable URI, a human-and-machine-readable manifest, a content-addressed history, and a resolver that connects them all.

In the same way that IPFS content-addressed files and OCI container-addressed images, PX is narrative-addressed — a universal namespace for the building blocks of stories.

Why PX?

Today, narrative assets live in silos:

• Worldbuilding docs in Notion or Google Docs
• Character sheets in spreadsheets
• Concept art in Dropbox or S3
• Scene breakdowns in Final Draft or Fade In
• AI prompts scattered across chat logs
• 3D assets on Sketchfab or Polycam

None of these tools talk to each other. PX unifies them under a single addressing and resolution layer.

px://toystory/character/woody
px://toystory/location/andys-room
px://toystory/scene/pizza-planet
px://toystory/prop/andy-hat

Installation

Installation Script

curl -fsSL https://github.com/portalshq/narrativeengine/releases/latest/download/install.sh | bash && npx skills add portalshq/narrativeengine

The one-liner installs the px CLI, the bundled px-mcp-server, and the agent skills. The MCP server is dormant by default; agent clients start it on demand over stdio so sandboxed agents can use PX through host-side CLI proxy calls.

Quick Start

# Initialize a repository (prompts for provider on first run)
px init toystory

# Initialize with local provider
px init toystory --provider local

# Configure provider only (no repository)
px init --provider local

# Initialize with remote provider
px init --provider remote --remote-url lore://127.0.0.1:41337 --workspace-id my-workspace

# Initialize with Portals Cloud
px auth login
px init --provider portals-cloud

# Inspect or clear the OS-keyring-backed session
px auth status
px auth logout

# Check system status
px status

# Run diagnostics
px doctor

# Run diagnostics with auto-repair
px doctor --repair

Portals Cloud uses grpcs://lore.portals.works on standard TLS port 443. Login is the only interactive VCS step; repository operations remain noninteractive and return an actionable px auth login error when credentials are missing or expired. Lore automatically exchanges the eight-hour login session for a five-minute token scoped to the single repository used by init, clone, pull, sync, push, and locking. CI uses a revocable service-account API key exchange; do not store long-lived bearer tokens in CI variables.

px install lore installs the exact portalshq/lore release compiled into that Px version. It downloads the installer from the same release tag, verifies its pinned SHA-256 before execution, and explicitly selects the Portals fork. It never executes the mutable main installer or silently falls back to an upstream Lore binary. Production release metadata binds this Lore client version to Px's signed checksum manifest.

CI reads the API key from its secret store and passes it to Lore over stdin, so the secret is absent from process arguments and command logs:

export PORTALS_CLOUD_API_KEY="${CI_PORTALS_CLOUD_API_KEY}"
px auth login --api-key

Use --api-key-env NAME to select a different secret environment variable.

Create a Repository

# Initialize a new repository
px init toystory

# See what you created
ls toystory/
# → .px/  repository.yaml  characters/  locations/  scenes/  props/

Create & Inspect Entities

# Create a character
px create character woody -u toystory -n "Woody"

# Create a location
px create location andys-room -u toystory -n "Andy's Room"

# Set properties
px set px://toystory/character/woody toy_type human
px set px://toystory/character/woody homeworld "px://toystory/location/andys-room"

# Resolve a manifest
px resolve px://toystory/character/woody

# Query a specific field
px resolve px://toystory/character/woody#properties.toy_type
# → human

# Resolve a subtree
px resolve px://toystory/character/woody properties

Version Control

# View commit history
px history px://toystory/character/woody

# Create branches
px branch toystory canon

# Sync with remote
px sync toystory

# Push to remote
px push toystory

Output Formats

px resolve px://toystory/character/woody -f json
px resolve px://toystory/character/woody -f yaml

Core Primitives

PX is built on four primitives:

1. URI — Identity

A px:// URI identifies any narrative resource. Version and branch are orthogonal selectors passed alongside the URI — never encoded in the path (mirrors Git, OCI, and package managers).

px://toystory/character/woody#references.appears_in
────┬── ───┬──── ────┬──── ──────┬────── ─────────────┬───────────
 scheme repository  entity_type entity_id          fragment (query)

2. Manifest — Current State

A YAML manifest is the durable representation of a narrative resource. It is simultaneously:

• Human-editable — readable by toybox-builders
• Machine-editable — structured, schema-validated
• Agent-readable — subtree-queryable for AI workflows
• Portable — no runtime dependency, just a file
• Signable — hash the content, sign the hash (Ed25519 in v0+)
• Versionable — the manifest is what gets committed

id: "px://toystory/character/woody"
name: "Woody"
entity_type: character
version: 17
properties:
  homeworld: "px://toystory/location/andys-room"
  toy_type: human
representations:
  reference_image:
    hash: "blake3:e3b0c44..."
    format: png
provenance:
  model: "midjourney-v6"
  prompt_hash: "blake3:abc123..."

3. Commit — History

Commits are content-addressed (BLAKE3) snapshots with patch metadata. Full history and revision identity live in the VCS, keeping manifests bounded and avoiding self-referential revision pointers.

4. Resolver — URI → Manifest

The resolver turns a px:// URI into a manifest (or a subtree of one). With optional selectors for branch or commit hash, it supports versioned resolution and fragment-based queries for efficient data access.

Scene Clips as Representations

Scenes can own generated video clips the same way characters own reference images. A generated clip is not usually a representation of one character; it is a representation of a scene, with references back to the characters, locations, props, and style guides that shaped it. A scene clip is stored as a content-addressed representation (for example clip-01, identified by its BLAKE3 hash), not as a field on any single character.

The scene manifest remains simple and durable:

id: "px://toystory/scene/pizza-planet"
name: "Pizza Planet"
entity_type: scene
version: 3
properties:
  summary: "Woody and Buzz enter a crowded pizza-planet while searching for passage off Andy's Room."
  time_of_day: night
  mood: tense
references:
  characters:
    - "px://toystory/character/woody"
    - "px://toystory/character/buzzlightyear"
  location: "px://toystory/location/pizza-planet"
representations:
  clip-01:
    hash: "blake3:af1349b9..."
    format: mp4
    uri: "clip-01.mp4"

When resolved with provenance, PX returns versioned per-file provenance for the manifest and each direct representation. This keeps generation metadata attached to the committed files without requiring users to manage the underlying VCS directly.

manifest:
  id: "px://toystory/scene/pizza-planet"
  name: "Pizza Planet"
  entity_type: scene
  version: 3
  representations:
    clip-01:
      hash: "blake3:af1349b9..."
      format: mp4
      uri: "clip-01.mp4"
provenance:
  revision: "a72c9f3b..."
  files:
    - role: manifest
      path: "scene/pizza-planet.yaml"
      provenance:
        px.provenance.kind: edit
        px.provenance.author: toybox-builder
    - role: representation
      name: clip-01
      path: "scene/clip-01.mp4"
      uri: "clip-01.mp4"
      hash: "blake3:af1349b9..."
      format: mp4
      provenance:
        px.provenance.kind: generation
        px.provenance.model: video-generator
        px.provenance.prompt.address: "blake3:b4d2..."

Entity Types

Repository Layout

Each repository is a Git repository on disk:

toystory/                    ← repository root (Git repo)
├── .px/
│   └── config.yaml          ← repository configuration
├── repository.yaml            ← world manifest
├── characters/
│   ├── woody.yaml
│   └── slinky.yaml
├── locations/
│   └── andys-room.yaml
├── scenes/
│   └── pizza-planet.yaml
└── props/

Primitives CLI Examples

Command-line examples for the core primitives, intended for humans working in a host shell. Agents must not execute these — agentic execution goes exclusively through px-mcp-server (see px-repo, px-resolve, px-update).

px create scene pizza-planet -u toystory -n "Pizza Planet"
px add px://toystory/scene/pizza-planet clip-01 ./pizza-planet-clip-01.mp4 --format mp4 -m "Add pizza-planet scene clip"

px resolve px://toystory/scene/pizza-planet --provenance

Representation downloads and presigned URLs

Create a temporary download URL with px presign 25th-chapter/character/nathan-gunn item. See the px presign reference for entity and representation arguments, file lookup, configuration, and SDK examples.

MCP Server (mandatory for agents)

Agents MUST issue all PX operations exclusively through the px-mcp-server MCP tools (px_<command>). The px CLI is NOT available for agentic use — never shell out, never follow px ... shell examples.

The standard PX installer bundles the native px-mcp-server binary with px. If the MCP server is missing or broken, rerun the standard PX installer from a host shell.

The MCP server is not a daemon; agent clients start it on demand over stdio (see docs/authored/mcp/install.md for client configuration), and it proxies tool calls to the host PX installation.

Available MCP Tools

Every PX command is available as an MCP tool with a px_ prefix and dashes/spaces converted to underscores. For example:

• px_resolve — resolve a PX URI to its manifest or a subtree
• px_create — create a new entity manifest
• px_query — query a subtree from a manifest
• px_set — set a property on an entity manifest
• px_add — add a file representation to an entity manifest
• px_commit — commit changes to a repository

Per-tool parameters are documented under docs/generated/mcp/<tool>.md (generated from the same command definitions as the MCP server itself). Tool arguments use MCP field names (for example branch, commit, format, include_blobs); pass the branch explicitly on every call that accepts one — do not rely on whichever branch happens to be checked out. The CLI reference (docs/generated/cli.md, docs/generated/commands/) and shell examples elsewhere in these docs are for humans in host shells only and MUST NOT be used as agent instructions.

MCP Server Configuration

Add to your agent's MCP configuration (e.g., ~/.codex/config.json):

{
  "mcpServers": {
    "px": {
      "command": "/bin/sh",
      "args": [
        "-lc",
        "PX_DIR=\"$HOME/.px\" exec px-mcp-server"
      ]
    }
  }
}

Connect with Codex

Codex stores MCP configuration in ~/.codex/config.toml alongside the rest of its config. The Codex CLI, the ChatGPT desktop app, and the IDE extension all share that MCP configuration, so you only need to register px once.

Add the server with the CLI:

codex mcp add px --env PX_DIR="$HOME/.px" -- /bin/sh -lc 'exec px-mcp-server'

If px-mcp-server is not on PATH, use the full installed path instead, usually ~/.local/bin/px-mcp-server or /usr/local/bin/px-mcp-server.

You can also configure it manually in ~/.codex/config.toml:

[mcp_servers.px]
command = "/bin/sh"
args = ["-lc", "PX_DIR=\"$HOME/.px\" exec px-mcp-server"]
enabled = true

Project-scoped config works too for trusted projects:

[mcp_servers.px]
command = "/bin/sh"
args = ["-lc", "PX_DIR=\"$HOME/.px\" exec px-mcp-server"]
enabled = true

Use the same block in .codex/config.toml inside a trusted project if you want the server scoped to that repository.

Connect with Claude Code

Register the server for your user account with the Claude Code CLI:

claude mcp add px --env PX_DIR="$HOME/.px" --scope user -- /bin/sh -lc 'exec px-mcp-server'

If px-mcp-server is not on PATH, use the full installed path instead, usually ~/.local/bin/px-mcp-server or /usr/local/bin/px-mcp-server.

Other MCP Clients

Claude Desktop and other MCP clients use the same stdio pattern. Add a server entry that runs the bundled px-mcp-server command on demand, and keep PX_DIR pointed at your PX workspace if you need a non-default data directory.

Example host-side launch command:

/bin/sh -lc 'PX_DIR="$HOME/.px" exec px-mcp-server'

Use the same command/args form in any client that supports stdio MCP servers.

Inside sandboxes, use the MCP tools for all PX operations. Direct px CLI commands are for humans in host-local shells only and MUST NOT be used as agent instructions.

PX CLI Reference

The px command-line interface (v0.9.0) provides tools for creating, resolving, and managing narrative resources using the PX protocol.

Command Overview

Global Options

Output Formats

Most commands support --format (-f) with values yaml (default) or json.

When stdout is not a terminal, JSON is used automatically. Override with $PX_OUTPUT.

Common Examples

# Initialize a repository
px init toystory

# Create an entity
px create character woody -u toystory -n "Woody"

# Resolve a manifest
px resolve px://toystory/character/woody

# Query a subtree
px query px://toystory/character/woody properties

# View commit history
px history px://toystory/character/woody

HTTP Server

The PX resolver server provides a REST API for resolution and commits.

# Start the server (defaults to port 3100, base path = current directory)
px-server

# Custom port and base path
PX_PORT=8080 PX_BASE_PATH=/path/to/repositories px-server

Configuration

PX core uses environment variables for configuration. All variables serve specific purposes with minimal overlap.

Storage Configuration

Lore VCS Configuration

See the presign reference for automatic provider endpoint selection, login reuse, and server key provisioning.

Constants

Note: The environment variable PX_DIR (storage base directory) and the constant PX_DIR (metadata directory name) serve different purposes and do not overlap.

Endpoints

Query parameters for resolution: branch, commit, path (subtree query).

CLI Command Reference

Complete reference for all px CLI commands.

Design Principles

1. Content-addressed — Every piece of content is identified by its cryptographic hash. Manifests are immutable once committed.

2. URI-addressed — Every entity has a stable, portable URI. URIs are never invalidated by renames or moves.

3. Human-readable — YAML manifests are readable by toybox-builders and AI agents alike.

4. Portable — No runtime dependencies. A manifest is just a YAML file. A repository is just a Git repo.

5. AI-native — Subtree queries let AI agents fetch exactly the data they need. Provenance tracking records generation metadata.

6. Schema-validated — All manifests conform to a JSON Schema. Invalid manifests are rejected at commit time.

7. Decentralized — Repositories are Git repositories. They can be cloned, forked, merged, and published independently.

8. Extensible — New entity types, representation formats, and merge strategies can be added without breaking existing data.

Status

This is a v0 prototype. APIs and formats may change.

License

MIT

Status

This is a v0 prototype. APIs and formats may change.

License

MIT