Skip to content

IPC protocol 0.2

Schema reference / IPC protocol / 0.2

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-07
Title
“Hyprune 0.2 ipc”
Dialect
JSON Schema 2020-12 · unknown fields rejected unless marked
Raw schemaipc.schema.json · 3,570 lines · 79 KB
DownloadOpen rawsha256 2ffc75616366…
Loading ipc.schema.json…

Changes since 0.1

Changelog · 0.2.0 — 2026-10-07

Adds frozen v0.2/ schemas for IPC 0.2 and world format 0.2; v0/ stays unchanged. The validator accepts an optional fourth version argument (default 0.1); CLI accepts [response-method|-] [contract-version].

Structural diff against 0.1: 26 entries added, 6 entries changed. Descriptions and $id changes are ignored.

32 changes
  • addeddestination
  • addedintegrations
  • addedlocation
  • addedmethod autodrive.start
  • addedmethod autodrive.stop
  • addedmethod camera.get
  • addedmethod camera.set
  • addedmethod data.publish
  • addedmethod data.remove
  • addedmethod route.clear
  • addedmethod route.set
  • addedmethod travel.cancel
  • addedmethod travel.start
  • addedmethod ui.close
  • addedmethod ui.open
  • addedmethod waypoint.clear
  • addedmethod waypoint.set
  • addednotification data.updated
  • addednotification location.transition
  • addednotification ui.closed
  • addednotification ui.opened
  • addedroutePoint
  • addedsource
  • addedtarget
  • addedtransition
  • addedwaypoint
  • changedmethod session.hello
    • ~ result.protocol "0.1" (required) → "0.2" (required)
    • ~ result.methods adds "runtime.exit", "camera.get", "camera.set", … (26 values))[]; removes "runtime.exit")[]
    • ~ result.events adds "session.revoked", "location.transition", "ui.opened", "ui.closed", "data.updated")[]; removes "session.revoked")[]
  • changednotification
    • ~ (definition) :state.delta.notification | runtime.notice.notification | session.revoked.notification → :state.delta.notification | runtime.notice.notification | session.revoked.notification | location.transition.notification | ui.opened.notification | ui.closed.notification | data.updated.notification
  • changednotification state.delta
    • + params.changes.location location
    • + params.changes.integrations integrations
  • changedrequest
    • ~ (definition) :session.hello.request | session.ping.request | state.subscribe.request | state.snapshot.request | state.unsubscribe.request | world.load.request | surface.focus.request | movement.set.request | shell.claim.request | shell.release.request | shell.overlay.request | runtime.exit.request → :session.hello.request | session.ping.request | state.subscribe.request | state.snapshot.request | state.unsubscribe.request | world.load.request | surface.focus.request | movement.set.request | shell.claim.request | shell.release.request | shell.overlay.request | runtime.exit.request | camera.get.request | camera.set.request | waypoint.set.request | waypoint.clear.request | route.set.request | route.clear.request | travel.start.request | travel.cancel.request | autodrive.start.request | autodrive.stop.request | ui.open.request | ui.close.request | data.publish.request | data.remove.request
  • changedresponse
    • ~ (definition) :session.hello.response | session.ping.response | state.subscribe.response | state.snapshot.response | state.unsubscribe.response | world.load.response | surface.focus.response | movement.set.response | shell.release.response | shell.overlay.response | runtime.exit.response | shell.claim.response → :session.hello.response | session.ping.response | state.subscribe.response | state.snapshot.response | state.unsubscribe.response | world.load.response | surface.focus.response | movement.set.response | shell.release.response | shell.overlay.response | runtime.exit.response | shell.claim.response | camera.get.response | camera.set.response | waypoint.set.response | waypoint.clear.response | route.set.response | route.clear.response | travel.start.response | travel.cancel.response | autodrive.start.response | autodrive.stop.response | ui.open.response | ui.close.response | data.publish.response | data.remove.response
  • changedstate
    • + location location (required)
    • + integrations integrations (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.2"
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" | … (26 values))[]items ≥ 0 · unique items
eventsrequired("state.delta" | "runtime.notice" | "session.revoked" | "location.transition" | "ui.opened" | "ui.closed" | "data.updated")[]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

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

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

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

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

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 2ffc756163665b449c6e35f09e034ca8c30ca69aaceaeaa9f44aeca1eade7399.