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

The installation script installs both px and px-mcp-server. 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.

Skills Install

Install these skills to use PX with agent workflows, including entity-aware prompts, generation templates, and the resolve/update steps that keep character and scene output consistent.

npx skills add portalshq/narrativeengine

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, push, pull, sync, publish, 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

# Publish to remote
px publish 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.

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"

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.

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

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/

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

The standard PX installer bundles the native px-mcp-server binary with px. If the MCP command 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, and it proxies tool calls to the host px CLI.

Agent Sandbox Integration

When running inside a sandboxed environment (e.g., Codex) without outbound network access, use MCP tools instead of shelling out to the px CLI directly. The MCP server runs on the host machine, starts only when the agent/MCP client launches it over stdio, and proxies tool calls to the host px CLI.

Direct px CLI examples in this skill are for humans, host-local shells, and non-sandboxed scripts. In an agent sandbox, use the MCP tools for any operation that may need Lore/cloud/network access.

Available MCP Tools

All px CLI commands are available as MCP tools with px_ prefix. For example:

• px resolve -> px_resolve tool
• px create -> px_create tool
• px set -> px_set tool

Prefer MCP tools over shell commands when in a sandbox.

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.

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 instead of shelling out to px directly for network-backed operations. Direct px CLI commands remain the right choice for humans and host-local shells.

PX CLI Reference

The px command-line interface (v0.8.19) 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