Skip to content

IPC protocol 0.5

Schema reference / IPC protocol / 0.5

JSON-RPC 2.0 frames between core and shells, SDK clients and tools: every method’s params and result, notifications, state and errors.

Status
Frozen · latest is 0.28
Published
2026-10-08
Title as published
“Hyprune 0.3 ipc” This title names 0.3, not 0.5. Published schemas are frozen byte-for-byte, so it is kept; the version on this page comes from the schema’s path and $id.
Dialect
JSON Schema 2020-12 · unknown fields rejected unless marked
Raw schemaipc.schema.json · 5,781 lines · 129 KB
DownloadOpen rawsha256 2744c0c8a8f4…
Loading ipc.schema.json…

Changes since 0.4

Changelog · 0.5.0 (M3A)

Frozen IPC 0.5 adds revisioned interaction mode/tool state, workspace app metadata, and custom surface pose/size placement rules. All prior schemas stay unchanged; world format remains 0.3. Tests cover exact version isolation, closed objects, bounded app/tool collections and complete custom placement records.

Structural diff against 0.4: 2 entries added, 5 entries changed. Descriptions and $id changes are ignored.

7 changes
  • addedapps
  • addedinteraction
  • changedmethod placements.list
    • ~ result.placements object[] (required) · items ≤ 128 → any of 2[] (required) · items ≤ 128
    • + result.placements[]|1 object
    • + result.placements[]|1.worldId id (required)
    • + result.placements[]|1.areaId slug (required)
    • + result.placements[]|1.anchorId slug (required)
    • + result.placements[]|1.rule object (required)
    • + result.placements[]|1.rule.appClass string (required) · length 1–256
    • + result.placements[]|1.rule.title string (required) · length ≤ 256
    • + result.placements[]| object
    • + result.placements[]|.worldId id (required)
    • + result.placements[]|.areaId slug (required)
    • + result.placements[]|.anchorId "" (required)
    • + result.placements[]|.rule object (required)
    • + result.placements[]|.rule.appClass string (required) · length 1–256
    • + result.placements[]|.rule.title string (required) · length ≤ 256
    • + result.placements[]|.pose pose (required)
    • + result.placements[]|.size size2 (required)
    • − result.placements[].worldId
    • − result.placements[].areaId
    • − result.placements[].anchorId
    • − result.placements[].rule
    • − result.placements[].rule.appClass
    • − result.placements[].rule.title
  • changedmethod session.hello
    • ~ result.protocol "0.4" (required) → "0.5" (required)
  • changedmounts
    • ~ placements object[] (required) · items ≤ 128 → any of 2[] (required) · items ≤ 128
    • + placements[]|1 object
    • + placements[]|1.worldId id (required)
    • + placements[]|1.areaId slug (required)
    • + placements[]|1.anchorId slug (required)
    • + placements[]|1.rule object (required)
    • + placements[]|1.rule.appClass string (required) · length 1–256
    • + placements[]|1.rule.title string (required) · length ≤ 256
    • + placements[]| object
    • + placements[]|.worldId id (required)
    • + placements[]|.areaId slug (required)
    • + placements[]|.anchorId "" (required)
    • + placements[]|.rule object (required)
    • + placements[]|.rule.appClass string (required) · length 1–256
    • + placements[]|.rule.title string (required) · length ≤ 256
    • + placements[]|.pose pose (required)
    • + placements[]|.size size2 (required)
    • − placements[].worldId
    • − placements[].areaId
    • − placements[].anchorId
    • − placements[].rule
    • − placements[].rule.appClass
    • − placements[].rule.title
  • changednotification state.delta
    • + params.changes.apps apps
    • + params.changes.interaction interaction
  • changedstate
    • + interaction interaction (required)
    • + apps apps (required)

Methods

Each method is a JSON-RPC 2.0 request {jsonrpc, id, method, params} answered by {jsonrpc, id, result} or an error. Params and results are listed below.

session.hello#

params · object

FieldTypeConstraints
protocolsrequiredstring[]items ≥ 1 · unique items · each length 1–256
clientrequiredobject
idrequiredid
namerequiredstringlength 1–256
capabilitiesrequiredcapability[]items ≥ 0 · unique items
tokenstringlength 64 · pattern ^[a-f0-9]{64}$

result · object

FieldTypeConstraints
protocolrequired"0.5"
sessionIdrequiredstringlength 1–128
capabilitiesrequiredcapability[]items ≥ 0 · unique items
methodsrequired("session.hello" | "session.ping" | "state.subscribe" | "state.snapshot" | "state.unsubscribe" | "world.load" | "surface.focus" | "movement.set" | "shell.claim" | "shell.release" | "shell.overlay" | "runtime.exit" | "camera.get" | "camera.set" | … (41 values))[]items ≥ 0 · unique items
eventsrequired("state.delta" | "runtime.notice" | "session.revoked" | "location.transition" | "ui.opened" | "ui.closed" | "data.updated" | "mounts.changed" | "presentation.changed")[]items ≥ 0 · unique items

session.ping#

params · {} (no fields)

result · object

FieldTypeConstraints
monotonicMsrequiredrevision

state.subscribe#

params · object

FieldTypeConstraints
topicsrequired["state"]

result · object

FieldTypeConstraints
subscriptionIdrequiredstringlength 1–128
snapshotrequiredsnapshot

state.snapshot#

params · object

FieldTypeConstraints
subscriptionIdrequiredstringlength 1–128

result · object

FieldTypeConstraints
snapshotrequiredsnapshot

state.unsubscribe#

params · object

FieldTypeConstraints
subscriptionIdrequiredstringlength 1–128

result · object

FieldTypeConstraints
okrequiredtrue

world.load#

params · object

FieldTypeConstraints
worldIdrequiredid
spawnIdslug

result · object

FieldTypeConstraints
revisionrequiredrevision

surface.focus#

params · object

FieldTypeConstraints
surfaceIdrequiredstringlength 1–128
intentrequired"pointer" | "keyboard"

result · object

FieldTypeConstraints
revisionrequiredrevision

movement.set#

params · object

FieldTypeConstraints
modeIdrequiredid

result · object

FieldTypeConstraints
revisionrequiredrevision

shell.claim#

params · object

FieldTypeConstraints
outputsrequiredstring[]items ≥ 1 · unique items · each length 1–128

result · object

FieldTypeConstraints
leaseIdrequiredstringlength 1–128
revisionrequiredrevision

shell.release#

params · object

FieldTypeConstraints
leaseIdrequiredstringlength 1–128

result · object

FieldTypeConstraints
revisionrequiredrevision

shell.overlay#

params · object

FieldTypeConstraints
leaseIdrequiredstringlength 1–128
outputIdrequiredstringlength 1–128
visiblerequiredboolean
exclusiveInputrequiredboolean

result · object

FieldTypeConstraints
revisionrequiredrevision

runtime.exit#

params · {} (no fields)

result · object

FieldTypeConstraints
revisionrequiredrevision

camera.get#

params · {} (no fields)

result · object

FieldTypeConstraints
positionrequirednumber[3]each ≥ -100000 · each ≤ 100000
orientationrequirednumber[4]

camera.set#

params · object

FieldTypeConstraints
positionrequirednumber[3]each ≥ -100000 · each ≤ 100000
orientationrequirednumber[4]

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

waypoint.set#

params · one of 2

FieldTypeConstraints
variant 1object
idrequiredstringlength 1–128
labelrequiredstringlength 1–256
targetrequiredtarget
variant 2object
idrequiredstringlength 1–128
labelrequiredstringlength 1–256
positionrequirednumber[3]each ≥ -100000 · each ≤ 100000

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

waypoint.clear#

params · {} (no fields)

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

route.set#

params · object

FieldTypeConstraints
pointsrequiredtarget[]items 1–64

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

route.clear#

params · {} (no fields)

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

travel.start#

params · object

FieldTypeConstraints
torequiredtarget
durationMsinteger≥ 0 · ≤ 10000

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

travel.cancel#

params · {} (no fields)

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

autodrive.start#

params · object

FieldTypeConstraints
speednumber≥ 0.1 · ≤ 10

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

autodrive.stop#

params · {} (no fields)

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

ui.open#

params · object

FieldTypeConstraints
leaseIdrequiredstringlength 1–128
outputIdrequiredstringlength 1–128
panelrequiredstringlength 1–128

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

ui.close#

params · object

FieldTypeConstraints
leaseIdrequiredstringlength 1–128
outputIdrequiredstringlength 1–128

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

data.publish#

params · object

FieldTypeConstraints
sourceIdrequiredid
valuesrequiredmap → number | boolean | stringentries ≤ 32 · keys: length ≤ 128
sequencerequiredinteger≥ 0 · ≤ 2⁵³−1
ttlMsinteger≥ 100 · ≤ 60000

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

data.remove#

params · object

FieldTypeConstraints
sourceIdrequiredid

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

shell.bind#

params · object

FieldTypeConstraints
leaseIdrequiredstringlength 1–128
pidrequiredinteger≥ 1 · ≤ 2147483647

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

workspace.activate#

params · object

FieldTypeConstraints
idrequiredinteger≥ 1 · ≤ 2147483647

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

workspace.bind#

params · object

FieldTypeConstraints
idrequiredinteger≥ 1 · ≤ 2147483647
worldIdrequiredid
areaIdrequiredslug

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

workspace.focus#

params · object

FieldTypeConstraints
idrequiredinteger≥ 1 · ≤ 2147483647

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

workspace.unfocus#

params · {} (no fields)

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

surface.pull#

params · object

FieldTypeConstraints
surfaceIdrequiredstringlength 1–256

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

surface.place#

params · object

FieldTypeConstraints
surfaceIdrequiredstringlength 1–256
anchorIdslug

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

surface.return#

params · object

FieldTypeConstraints
surfaceIdrequiredstringlength 1–256

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

placements.list#

params · {} (no fields)

result · object

FieldTypeConstraints
placementsrequiredany of 2[]items ≤ 128
variant 1object
worldIdrequiredid
areaIdrequiredslug
anchorIdrequiredslug
rulerequiredobject
appClassrequiredstringlength 1–256
titlerequiredstringlength ≤ 256
when anchorId = ""object
worldIdrequiredid
areaIdrequiredslug
anchorIdrequired""
rulerequiredobject
appClassrequiredstringlength 1–256
titlerequiredstringlength ≤ 256
poserequiredpose
sizerequiredsize2

placements.remove#

params · object

FieldTypeConstraints
worldIdrequiredid
areaIdrequiredslug
rulerequiredobject
appClassrequiredstringlength 1–256
titlerequiredstringlength ≤ 256

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

data.object.bind#

params · object

FieldTypeConstraints
objectIdrequiredslug
sourceIdrequiredid

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

atmosphere.get#

params · {} (no fields)

result · object

FieldTypeConstraints
profilerequirednull | atmosphere
qualityrequired"high" | "intel"

atmosphere.set#

params · object

FieldTypeConstraints
profilerequiredatmosphere

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

camera.fov#

params · object

FieldTypeConstraints
degreesrequirednumber≥ 30 · ≤ 110

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

surfaces.recall#

params · {} (no fields)

result · object

FieldTypeConstraints
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

Notifications

state.delta#

params · object

FieldTypeConstraints
subscriptionIdrequiredstringlength 1–128
sessionIdrequiredstringlength 1–128
baseRevisionrequiredrevision
revisionrequiredrevision
changesrequiredobjectentries ≥ 1
runtimeobject
activerequiredboolean
outputsrequiredstring[]items ≥ 0 · unique items · each length 1–128
worldany of 2
variant 1null
variant 2object
idrequiredid
spawnIdrequiredslug
surfacesobject[]items ≥ 0
idrequiredstringlength 1–128
kindrequired"window" | "workspace" | "layer" | "web" | "custom"
titlerequiredstringlength 0–512
logicalSizerequirednumber[2]each > 0
focusedrequiredboolean
movementobject
modeIdrequiredid
positionrequirednumber[3]
orientationrequirednumber[4]
shellobject
leasesrequiredobject[]items ≥ 0
idrequiredstringlength 1–128
outputsrequiredstring[]items ≥ 1 · unique items · each length 1–128
overlaysrequiredobject[]items ≥ 0
outputIdrequiredstringlength 1–128
visiblerequiredboolean
exclusiveInputrequiredboolean
locationlocation
integrationsintegrations
spatialspatial
workspacesworkspaces
mountsmounts
presentationpresentation
appsapps
interactioninteraction

runtime.notice#

params · object

FieldTypeConstraints
levelrequired"info" | "warning" | "error"
coderequiredstringlength 1–256
messagerequiredstringlength 1–4096

session.revoked#

params · object

FieldTypeConstraints
reasonrequiredstringlength 1–4096

location.transition#

params · object

FieldTypeConstraints
phaserequired"departing" | "travelling" | "arrived" | "cancelled" | "loading" | "failed"
progressrequirednull | number
torequireddestination
sessionIdrequiredstringlength 1–128
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1
idrequiredstringlength 1–128
outputIdrequirednull | string
monotonicMsrequiredinteger≥ 0 · ≤ 2⁵³−1

ui.opened#

params · object

FieldTypeConstraints
leaseIdrequiredstringlength 1–128
outputIdrequiredstringlength 1–128
panelrequiredstringlength 1–128
sessionIdrequiredstringlength 1–128
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

ui.closed#

params · object

FieldTypeConstraints
leaseIdrequiredstringlength 1–128
outputIdrequiredstringlength 1–128
sessionIdrequiredstringlength 1–128
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

data.updated#

params · object

FieldTypeConstraints
sourceIdrequiredid
valuesrequiredmap → number | boolean | stringentries ≤ 32 · keys: length ≤ 128
sequencerequiredinteger≥ 0 · ≤ 2⁵³−1
monotonicMsrequiredinteger≥ 0 · ≤ 2⁵³−1
ttlMsrequiredinteger≥ 100 · ≤ 60000
sessionIdrequiredstringlength 1–128
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1

mounts.changed#

params · object

FieldTypeConstraints
sessionIdrequiredstringlength 1–256
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1
mountsrequiredmounts

presentation.changed#

params · object

FieldTypeConstraints
sessionIdrequiredstringlength 1–256
revisionrequiredinteger≥ 0 · ≤ 2⁵³−1
presentationrequiredpresentation

Types

state#

object

FieldTypeConstraints
runtimerequiredobject
activerequiredboolean
outputsrequiredstring[]items ≥ 0 · unique items · each length 1–128
worldrequiredany of 2
variant 1null
variant 2object
idrequiredid
spawnIdrequiredslug
surfacesrequiredobject[]items ≥ 0
idrequiredstringlength 1–128
kindrequired"window" | "workspace" | "layer" | "web" | "custom"
titlerequiredstringlength 0–512
logicalSizerequirednumber[2]each > 0
focusedrequiredboolean
movementrequiredobject
modeIdrequiredid
positionrequirednumber[3]
orientationrequirednumber[4]
shellrequiredobject
leasesrequiredobject[]items ≥ 0
idrequiredstringlength 1–128
outputsrequiredstring[]items ≥ 1 · unique items · each length 1–128
overlaysrequiredobject[]items ≥ 0
outputIdrequiredstringlength 1–128
visiblerequiredboolean
exclusiveInputrequiredboolean
locationrequiredlocation
integrationsrequiredintegrations
spatialrequiredspatial
workspacesrequiredworkspaces
mountsrequiredmounts
presentationrequiredpresentation
interactionrequiredinteraction
appsrequiredapps

snapshot#

object

FieldTypeConstraints
sessionIdrequiredstringlength 1–128
revisionrequiredrevision
staterequiredstate

target#

one of 2

FieldTypeConstraints
variant 1object
positionrequirednumber[3]each ≥ -100000 · each ≤ 100000
variant 2object
zoneIdrequiredstringlength 1–128

transition#

object

FieldTypeConstraints
phaserequired"departing" | "travelling" | "arrived" | "cancelled" | "loading" | "failed"
progressrequirednull | number
torequireddestination
idrequiredstringlength 1–128
outputIdrequirednull | string
monotonicMsrequiredinteger≥ 0 · ≤ 2⁵³−1

waypoint#

object

FieldTypeConstraints
idrequiredstringlength 1–128
labelrequiredstringlength 1–256
targetrequiredtarget
positionrequirednumber[3]each ≥ -100000 · each ≤ 100000

routePoint#

object

FieldTypeConstraints
targetrequiredtarget
positionrequirednumber[3]each ≥ -100000 · each ≤ 100000

source#

object

FieldTypeConstraints
sourceIdrequiredid
valuesrequiredmap → number | boolean | stringentries ≤ 32 · keys: length ≤ 128
sequencerequiredinteger≥ 0 · ≤ 2⁵³−1
monotonicMsrequiredinteger≥ 0 · ≤ 2⁵³−1
ttlMsrequiredinteger≥ 100 · ≤ 60000

location#

object

FieldTypeConstraints
zonesrequiredWorld zones
waypointrequirednull | waypoint
routerequiredroutePoint[]items 0–64
autodriverequiredboolean
transitionrequirednull | transition

integrations#

object

FieldTypeConstraints
sourcesrequiredsource[]items 0–32

destination#

one of 2

FieldTypeConstraints
variant 1target
variant 2object
worldIdrequiredid
spawnIdslug

map#

object

FieldTypeConstraints
svgrequiredstringlength 1–65536
sha256requiredstringpattern ^[a-f0-9]{64}$
boundsrequirednumber[4]
worldToMaprequirednumber[6]

marker#

object

FieldTypeConstraints
idrequiredstringlength 1–128
labelrequiredstringlength ≤ 256
xrequirednumber≥ 0 · ≤ 1
yrequirednumber≥ 0 · ≤ 1
distancerequirednumber≥ 0
occludedrequiredboolean

spatial#

object

FieldTypeConstraints
worldrequiredany of 2
variant 1null
variant 2object
idrequiredid
namerequiredstringlength ≤ 256
placesrequiredobject[]items ≤ 64
idrequiredstringlength 1–128
namerequiredstringlength ≤ 256
positionrequirednumber[3]
maprequirednull | map
outputrequiredany of 2
variant 1null
variant 2object
idrequiredstringlength 1–128
namerequiredstringlength 1–128
widthrequiredinteger≥ 1
heightrequiredinteger≥ 1
scalerequirednumber> 0
projectionrequiredany of 2
variant 1null
variant 2object
outputIdrequiredstringlength 1–128
worldIdrequiredid
monotonicMsrequiredinteger≥ 0
markersrequiredmarker[]items ≤ 64

workspaces#

object

FieldTypeConstraints
currentIdrequirednull | integer
locationsrequiredobject[]items ≤ 32
idrequiredinteger≥ 1 · ≤ 2147483647
labelrequiredstringlength ≤ 256
worldIdrequiredid
spawnIdrequiredslug

mounts#

object

FieldTypeConstraints
areasrequiredarea[]items ≤ 32
anchorsrequiredobject[]items ≤ 128
idrequiredslug
poserequiredpose
sizerequiredsize2
mountrequiredmount
areaIdrequiredslug
bindingsrequiredobject[]items ≤ 32
idrequiredinteger≥ 1 · ≤ 2147483647
worldIdrequiredid
areaIdrequiredslug
placementsrequiredany of 2[]items ≤ 128
variant 1object
worldIdrequiredid
areaIdrequiredslug
anchorIdrequiredslug
rulerequiredobject
appClassrequiredstringlength 1–256
titlerequiredstringlength ≤ 256
when anchorId = ""object
worldIdrequiredid
areaIdrequiredslug
anchorIdrequired""
rulerequiredobject
appClassrequiredstringlength 1–256
titlerequiredstringlength ≤ 256
poserequiredpose
sizerequiredsize2
objectsrequiredobject[]items ≤ 128
idrequiredslug
areaIdrequiredslug
poserequiredpose
mountTyperequired"facade-wall" | "hanging-wall" | "wall-inset-console" | "banner" | "lectern" | "operator-desk" | "field-rig" | "kiosk-pillar" | "globe" | "crate" | "blast-door-screen" | "terminal-bench" | "radar-dish"
sourceIdrequirednull | id
carriedSurfaceIdrequirednull | string
desktopWorkspaceIdrequirednull | integer
placementZonesrequiredplacementZone[]items ≤ 32
instancesrequiredobject[]items ≤ 16
surfaceIdrequiredstringlength 1–128
workspaceIdrequiredinteger≥ 1
areaIdrequiredslug
anchorIdrequiredstringlength ≤ 128
statusrequired"carried" | "placed" | "recalled"

presentation#

object

FieldTypeConstraints
profilerequirednull | atmosphere
fovrequirednumber≥ 30 · ≤ 110
qualityrequired"high" | "intel"

interaction#

object

FieldTypeConstraints
moderequired"movement" | "typing" | "workspace" | "fullscreen"
toolrequiredinteger≥ 1 · ≤ 5
toolsrequired("pointer" | "mount" | "path")[5]
nocliprequiredboolean
cursorrequired"desktop" | "workspace" | "fullscreen" | "director" | "virtual" | "reticle"
taggedSurfaceIdrequirednull | string

apps#

object[] · items ≤ 16

FieldTypeConstraints
surfaceIdrequiredstringlength 1–128
workspaceIdrequiredinteger≥ 0
titlerequiredstringlength ≤ 512
appClassrequiredstringlength ≤ 256
iconrequiredstringlength ≤ 256

Frame envelopes

error#

object

FieldTypeConstraints
jsonrpcrequired"2.0"
idrequiredstring | null
errorrequiredobject
coderequired-32700 | -32600 | -32601 | -32602 | -32603 | -32008 | -32007 | -32006 | -32005 | -32004 | -32003 | -32002 | -32001
messagerequiredstringlength 1–4096
dataobject
retryablerequiredboolean

Mirrored byte-for-byte from hyprune/schema at 34849da45183 (2026-10-15). SHA-256 2744c0c8a8f416ec33a1dd3d688a5bbe3bd7fc6193c17860334b317d181fe3b9.