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

# Query a subtree
px query 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

Type	Example URI	Description
character	px://toystory/character/woody	Persistent character with identity across scenes/episodes
location	px://toystory/location/andys-room	Spatial location within a fictional repository
scene	px://toystory/scene/pizza-planet	Narrative scene — participants, timeline, events
prop	px://toystory/prop/andy-hat	Physical object with materials, variants, ownership
group	px://toystory/group/buzz-and-woody-flying	Mixed-media groups
world	px://toystory/world/toystory	The repository itself — rules, canon, top-level metadata

---

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.8.25) provides tools for creating, resolving, and managing narrative resources using the PX protocol.

Command Overview

Command	Description
`px add`	Add a file representation to an entity manifest
`px auth`	Manage secure authentication for the configured Lore provider
`px branch`	Create or list branches
`px commit`	Commit changes to a repository repository
`px completions`	Generate shell completions for `px`
`px configure`	Configure version-control backend (unified: replaces `px choose` + `px backend`)
`px content-hash`	Compute the BLAKE3 content hash of a file
`px create`	Create a new entity manifest
`px diff`	Show diff between two manifest files or versions
`px doctor`	Run diagnostics and repair
`px head`	Show the current HEAD commit hash
`px history`	View commit history for an entity
`px init`	Initialize a repository repository and/or configure the backend provider
`px install`	Install required dependencies
`px list`	List repositories or entities within a repository
`px merge`	Three-way merge of JSON/YAML values
`px presign`	Create a time-limited public URL for a committed representation
`px pull`	Clone or pull a repository from a remote
`px push`	Push the current branch to its configured upstream remote
`px query`	Query a subtree from a manifest
`px remote`	Manage remotes on a repository
`px resolve`	Resolve a PX URI to its manifest or a subtree
`px revert`	Revert a commit by hash (undoes all changes in that commit)
`px schema`	Print a JSON Schema for manifest or commit types
`px set`	Set a property on an entity manifest
`px status`	Show system status
`px switch`	Switch to a branch
`px sync`	Sync with remote
`px validate`	Validate a manifest against the PX schema

Global Options

Flag	Description	Default
--local	Resolve repository reads from an explicitly checked-out local working tree
--remote	Resolve repository reads through the configured Lore server (the default)
-d, --base-dir	Base directory for repository repositories. Defaults to $PX_DIR, or ~/.px if unset
-v, --verbose	Enable verbose debug logging

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

Variable	Purpose	Default	Required
PX_STORAGE_BACKEND	Storage backend selection (local or s3)	local	No
PX_DIR	Base directory for local storage	~/.px	No (local)
PX_S3_BUCKET	S3 bucket name	—	Yes (s3)
AWS_ACCESS_KEY_ID	AWS/R2 access key	—	Yes (s3)
AWS_SECRET_ACCESS_KEY	AWS/R2 secret key	—	Yes (s3)
AWS_REGION	AWS region	—	Yes (s3)
AWS_ENDPOINT_URL_S3	Custom S3 endpoint (R2, MinIO)	—	No (s3)
AWS_ENDPOINT_URL	Fallback S3 endpoint if AWS_ENDPOINT_URL_S3 unset	—	No (s3)

Lore VCS Configuration

Variable	Purpose	Default	Required
PX_LORE_URL_BASE	Lore server URL base	lore://localhost:8700	No
PX_WORKSPACE_ID	Workspace identifier for multi-tenancy	default	No
PXLORE_CLI	Path to lore CLI binary	lore (from PATH)	No
PX_LORE_GRPC_ENDPOINT	gRPC endpoint for branch ref sync	—	No (optional)
PX_LORE_GRPC_TOKEN	JWT bearer token for gRPC auth	—	No (optional)
PX_LORE_GRPC_RID	Repository ID (hex-encoded) for gRPC	—	No (optional)
PX_LORE_GRPC_INSECURE	Skip TLS verification (1/true/yes)	0	No (optional)
PX_LORE_HTTP_URL	Explicit Lore HTTP origin for presigned URLs	http://127.0.0.1:41339 for local Lore	No
PX_LORE_HTTP_TOKEN	Repository-scoped bearer token for Lore HTTP presign requests	Falls back to PX_LORE_GRPC_TOKEN, then the active Lore login	No

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

Constants

Constant	Value	Purpose
PX_DIR (const)	.px	Metadata directory name within repositories

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

Method	Path	Description
GET	/resolve/{repository}/{entity_type}/{entity_id}	Resolve a manifest
GET	/resolve/{repository}/{entity_type}/{entity_id}?branch=canon	Resolve at a branch
POST	/commit/{repository}/{entity_type}/{entity_id}	Commit changes
GET	/history/{repository}/{entity_type}/{entity_id}	Get commit history
GET	/repositories	List all repositories
GET	/repositories/{repository}/entities	List entities in a repository
GET	/health	Health check

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

---

CLI Command Reference

Complete reference for all px CLI commands.

Command	Description
`px add`	Add a file representation to an entity manifest
`px auth`	Manage secure authentication for the configured Lore provider
`px branch`	Create or list branches
`px commit`	Commit changes to a repository repository
`px completions`	Generate shell completions for `px`
`px configure`	Configure version-control backend (unified: replaces `px choose` + `px backend`)
`px content-hash`	Compute the BLAKE3 content hash of a file
`px create`	Create a new entity manifest
`px diff`	Show diff between two manifest files or versions
`px doctor`	Run diagnostics and repair
`px head`	Show the current HEAD commit hash
`px history`	View commit history for an entity
`px init`	Initialize a repository repository and/or configure the backend provider
`px install`	Install required dependencies
`px list`	List repositories or entities within a repository
`px merge`	Three-way merge of JSON/YAML values
`px presign`	Create a time-limited public URL for a committed representation
`px pull`	Clone or pull a repository from a remote
`px push`	Push the current branch to its configured upstream remote
`px query`	Query a subtree from a manifest
`px remote`	Manage remotes on a repository
`px resolve`	Resolve a PX URI to its manifest or a subtree
`px revert`	Revert a commit by hash (undoes all changes in that commit)
`px schema`	Print a JSON Schema for manifest or commit types
`px set`	Set a property on an entity manifest
`px status`	Show system status
`px switch`	Switch to a branch
`px sync`	Sync with remote
`px validate`	Validate a manifest against the PX schema

---

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