Skip to content

IPC protocol 0.3

Schema reference / IPC protocol / 0.3

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.3 ipc”
Dialect
JSON Schema 2020-12 · unknown fields rejected unless marked
Raw schemaipc.schema.json · 4,044 lines · 90 KB
DownloadOpen rawsha256 815e3bd2dac3…
Loading ipc.schema.json…

Changes since 0.2

Changelog · 0.3.0 — first real session

Frozen IPC 0.3 adds verified shell Wayland-child binding, workspace activation, revisioned safe inline map/metadata, selected-output descriptor and core-projected markers. 0.1/0.2 and world formats remain frozen. New positive/negative tests cover version isolation, reserved parameters, PID/workspace bounds and marker clipping.

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

11 changes
  • addedmap
  • addedmarker
  • addedmethod shell.bind
  • addedmethod workspace.activate
  • addedspatial
  • addedworkspaces
  • changedmethod session.hello
    • ~ result.protocol "0.2" (required) → "0.3" (required)
    • ~ result.methods adds … (28 values))[]; removes … (26 values))[]
  • changednotification state.delta
    • + params.changes.spatial spatial
    • + params.changes.workspaces workspaces
  • 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 | 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 → :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 | shell.bind.request | workspace.activate.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 | 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 → :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 | shell.bind.response | workspace.activate.response
  • changedstate
    • + spatial spatial (required)
    • + workspaces workspaces (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.3"
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" | … (28 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

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

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

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
spatialrequiredspatial
workspacesrequiredworkspaces

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

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 815e3bd2dac366bde101c9f81adf95b4f587ade4bbed42f880ce2949e9f2c5d3.