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.
Raw schema
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 fourthversionargument (default0.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
- added
destination - added
integrations - added
location - added
method autodrive.start - added
method autodrive.stop - added
method camera.get - added
method camera.set - added
method data.publish - added
method data.remove - added
method route.clear - added
method route.set - added
method travel.cancel - added
method travel.start - added
method ui.close - added
method ui.open - added
method waypoint.clear - added
method waypoint.set - added
notification data.updated - added
notification location.transition - added
notification ui.closed - added
notification ui.opened - added
routePoint - added
source - added
target - added
transition - added
waypoint - changed
method session.hello- ~
result.protocol"0.1" (required) → "0.2" (required) - ~
result.methodsadds "runtime.exit", "camera.get", "camera.set", … (26 values))[]; removes "runtime.exit")[] - ~
result.eventsadds "session.revoked", "location.transition", "ui.opened", "ui.closed", "data.updated")[]; removes "session.revoked")[]
- ~
- changed
notification- ~
(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
- ~
- changed
notification state.delta- +
params.changes.locationlocation - +
params.changes.integrationsintegrations
- +
- changed
request- ~
(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
- ~
- changed
response- ~
(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
- ~
- changed
state- +
locationlocation (required) - +
integrationsintegrations (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.hellosession.pingstate.subscribestate.snapshotstate.unsubscribeworld.loadsurface.focusmovement.setshell.claimshell.releaseshell.overlayruntime.exitcamera.getcamera.setwaypoint.setwaypoint.clearroute.setroute.cleartravel.starttravel.cancelautodrive.startautodrive.stopui.openui.closedata.publishdata.remove
session.hello#
params · object
| Field | Type | Constraints |
|---|---|---|
protocolsrequired | string[] | items ≥ 1 · unique items · each length 1–256 |
clientrequired | object | |
idrequired | id | |
namerequired | string | length 1–256 |
capabilitiesrequired | capability[] | items ≥ 0 · unique items |
token | string | length 64 · pattern ^[a-f0-9]{64}$ |
result · object
| Field | Type | Constraints |
|---|---|---|
protocolrequired | "0.2" | |
sessionIdrequired | string | length 1–128 |
capabilitiesrequired | capability[] | 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 |
state.subscribe#
params · object
| Field | Type | Constraints |
|---|---|---|
topicsrequired | ["state"] |
result · object
| Field | Type | Constraints |
|---|---|---|
subscriptionIdrequired | string | length 1–128 |
snapshotrequired | snapshot |
state.snapshot#
params · object
| Field | Type | Constraints |
|---|---|---|
subscriptionIdrequired | string | length 1–128 |
result · object
| Field | Type | Constraints |
|---|---|---|
snapshotrequired | snapshot |
state.unsubscribe#
params · object
| Field | Type | Constraints |
|---|---|---|
subscriptionIdrequired | string | length 1–128 |
result · object
| Field | Type | Constraints |
|---|---|---|
okrequired | true |
surface.focus#
params · object
| Field | Type | Constraints |
|---|---|---|
surfaceIdrequired | string | length 1–128 |
intentrequired | "pointer" | "keyboard" |
result · object
| Field | Type | Constraints |
|---|---|---|
revisionrequired | revision |
movement.set#
params · object
| Field | Type | Constraints |
|---|---|---|
modeIdrequired | id |
result · object
| Field | Type | Constraints |
|---|---|---|
revisionrequired | revision |
shell.claim#
params · object
| Field | Type | Constraints |
|---|---|---|
outputsrequired | string[] | items ≥ 1 · unique items · each length 1–128 |
result · object
| Field | Type | Constraints |
|---|---|---|
leaseIdrequired | string | length 1–128 |
revisionrequired | revision |
shell.release#
params · object
| Field | Type | Constraints |
|---|---|---|
leaseIdrequired | string | length 1–128 |
result · object
| Field | Type | Constraints |
|---|---|---|
revisionrequired | revision |
shell.overlay#
params · object
| Field | Type | Constraints |
|---|---|---|
leaseIdrequired | string | length 1–128 |
outputIdrequired | string | length 1–128 |
visiblerequired | boolean | |
exclusiveInputrequired | boolean |
result · object
| Field | Type | Constraints |
|---|---|---|
revisionrequired | revision |
camera.get#
params · {} (no fields)
result · object
| Field | Type | Constraints |
|---|---|---|
positionrequired | number[3] | each ≥ -100000 · each ≤ 100000 |
orientationrequired | number[4] |
camera.set#
params · object
| Field | Type | Constraints |
|---|---|---|
positionrequired | number[3] | each ≥ -100000 · each ≤ 100000 |
orientationrequired | number[4] |
result · object
| Field | Type | Constraints |
|---|---|---|
revisionrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
waypoint.set#
params · one of 2
| Field | Type | Constraints |
|---|---|---|
variant 1 | object | |
idrequired | string | length 1–128 |
labelrequired | string | length 1–256 |
targetrequired | target | |
variant 2 | object | |
idrequired | string | length 1–128 |
labelrequired | string | length 1–256 |
positionrequired | number[3] | each ≥ -100000 · each ≤ 100000 |
result · object
| Field | Type | Constraints |
|---|---|---|
revisionrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
waypoint.clear#
params · {} (no fields)
result · object
| Field | Type | Constraints |
|---|---|---|
revisionrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
route.set#
params · object
| Field | Type | Constraints |
|---|---|---|
pointsrequired | target[] | items 1–64 |
result · object
| Field | Type | Constraints |
|---|---|---|
revisionrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
route.clear#
params · {} (no fields)
result · object
| Field | Type | Constraints |
|---|---|---|
revisionrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
travel.start#
params · object
| Field | Type | Constraints |
|---|---|---|
torequired | target | |
durationMs | integer | ≥ 0 · ≤ 10000 |
result · object
| Field | Type | Constraints |
|---|---|---|
revisionrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
travel.cancel#
params · {} (no fields)
result · object
| Field | Type | Constraints |
|---|---|---|
revisionrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
autodrive.start#
params · object
| Field | Type | Constraints |
|---|---|---|
speed | number | ≥ 0.1 · ≤ 10 |
result · object
| Field | Type | Constraints |
|---|---|---|
revisionrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
autodrive.stop#
params · {} (no fields)
result · object
| Field | Type | Constraints |
|---|---|---|
revisionrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
ui.open#
params · object
| Field | Type | Constraints |
|---|---|---|
leaseIdrequired | string | length 1–128 |
outputIdrequired | string | length 1–128 |
panelrequired | string | length 1–128 |
result · object
| Field | Type | Constraints |
|---|---|---|
revisionrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
ui.close#
params · object
| Field | Type | Constraints |
|---|---|---|
leaseIdrequired | string | length 1–128 |
outputIdrequired | string | length 1–128 |
result · object
| Field | Type | Constraints |
|---|---|---|
revisionrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
Notifications
state.delta#
params · object
| Field | Type | Constraints |
|---|---|---|
subscriptionIdrequired | string | length 1–128 |
sessionIdrequired | string | length 1–128 |
baseRevisionrequired | revision | |
revisionrequired | revision | |
changesrequired | object | entries ≥ 1 |
runtime | object | |
activerequired | boolean | |
outputsrequired | string[] | items ≥ 0 · unique items · each length 1–128 |
world | any of 2 | |
variant 1 | null | |
variant 2 | object | |
idrequired | id | |
spawnIdrequired | slug | |
surfaces | object[] | items ≥ 0 |
idrequired | string | length 1–128 |
kindrequired | "window" | "workspace" | "layer" | "web" | "custom" | |
titlerequired | string | length 0–512 |
logicalSizerequired | number[2] | each > 0 |
focusedrequired | boolean | |
movement | object | |
modeIdrequired | id | |
positionrequired | number[3] | |
orientationrequired | number[4] | |
shell | object | |
leasesrequired | object[] | items ≥ 0 |
idrequired | string | length 1–128 |
outputsrequired | string[] | items ≥ 1 · unique items · each length 1–128 |
overlaysrequired | object[] | items ≥ 0 |
outputIdrequired | string | length 1–128 |
visiblerequired | boolean | |
exclusiveInputrequired | boolean | |
location | location | |
integrations | integrations |
runtime.notice#
params · object
| Field | Type | Constraints |
|---|---|---|
levelrequired | "info" | "warning" | "error" | |
coderequired | string | length 1–256 |
messagerequired | string | length 1–4096 |
location.transition#
params · object
| Field | Type | Constraints |
|---|---|---|
phaserequired | "departing" | "travelling" | "arrived" | "cancelled" | "loading" | "failed" | |
progressrequired | null | number | |
torequired | destination | |
sessionIdrequired | string | length 1–128 |
revisionrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
idrequired | string | length 1–128 |
outputIdrequired | null | string | |
monotonicMsrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
ui.opened#
params · object
| Field | Type | Constraints |
|---|---|---|
leaseIdrequired | string | length 1–128 |
outputIdrequired | string | length 1–128 |
panelrequired | string | length 1–128 |
sessionIdrequired | string | length 1–128 |
revisionrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
ui.closed#
params · object
| Field | Type | Constraints |
|---|---|---|
leaseIdrequired | string | length 1–128 |
outputIdrequired | string | length 1–128 |
sessionIdrequired | string | length 1–128 |
revisionrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
data.updated#
params · object
| Field | Type | Constraints |
|---|---|---|
sourceIdrequired | id | |
valuesrequired | map → number | boolean | string | entries ≤ 32 · keys: length ≤ 128 |
sequencerequired | integer | ≥ 0 · ≤ 2⁵³−1 |
monotonicMsrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
ttlMsrequired | integer | ≥ 100 · ≤ 60000 |
sessionIdrequired | string | length 1–128 |
revisionrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
Types
state#
object
| Field | Type | Constraints |
|---|---|---|
runtimerequired | object | |
activerequired | boolean | |
outputsrequired | string[] | items ≥ 0 · unique items · each length 1–128 |
worldrequired | any of 2 | |
variant 1 | null | |
variant 2 | object | |
idrequired | id | |
spawnIdrequired | slug | |
surfacesrequired | object[] | items ≥ 0 |
idrequired | string | length 1–128 |
kindrequired | "window" | "workspace" | "layer" | "web" | "custom" | |
titlerequired | string | length 0–512 |
logicalSizerequired | number[2] | each > 0 |
focusedrequired | boolean | |
movementrequired | object | |
modeIdrequired | id | |
positionrequired | number[3] | |
orientationrequired | number[4] | |
shellrequired | object | |
leasesrequired | object[] | items ≥ 0 |
idrequired | string | length 1–128 |
outputsrequired | string[] | items ≥ 1 · unique items · each length 1–128 |
overlaysrequired | object[] | items ≥ 0 |
outputIdrequired | string | length 1–128 |
visiblerequired | boolean | |
exclusiveInputrequired | boolean | |
locationrequired | location | |
integrationsrequired | integrations |
snapshot#
object
target#
one of 2
| Field | Type | Constraints |
|---|---|---|
variant 1 | object | |
positionrequired | number[3] | each ≥ -100000 · each ≤ 100000 |
variant 2 | object | |
zoneIdrequired | string | length 1–128 |
transition#
object
| Field | Type | Constraints |
|---|---|---|
phaserequired | "departing" | "travelling" | "arrived" | "cancelled" | "loading" | "failed" | |
progressrequired | null | number | |
torequired | destination | |
idrequired | string | length 1–128 |
outputIdrequired | null | string | |
monotonicMsrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
waypoint#
object
| Field | Type | Constraints |
|---|---|---|
idrequired | string | length 1–128 |
labelrequired | string | length 1–256 |
targetrequired | target | |
positionrequired | number[3] | each ≥ -100000 · each ≤ 100000 |
routePoint#
object
| Field | Type | Constraints |
|---|---|---|
targetrequired | target | |
positionrequired | number[3] | each ≥ -100000 · each ≤ 100000 |
source#
object
| Field | Type | Constraints |
|---|---|---|
sourceIdrequired | id | |
valuesrequired | map → number | boolean | string | entries ≤ 32 · keys: length ≤ 128 |
sequencerequired | integer | ≥ 0 · ≤ 2⁵³−1 |
monotonicMsrequired | integer | ≥ 0 · ≤ 2⁵³−1 |
ttlMsrequired | integer | ≥ 100 · ≤ 60000 |
location#
object
| Field | Type | Constraints |
|---|---|---|
zonesrequired | World zones | |
waypointrequired | null | waypoint | |
routerequired | routePoint[] | items 0–64 |
autodriverequired | boolean | |
transitionrequired | null | transition |
Frame envelopes
error#
object
| Field | Type | Constraints |
|---|---|---|
jsonrpcrequired | "2.0" | |
idrequired | string | null | |
errorrequired | object | |
coderequired | -32700 | -32600 | -32601 | -32602 | -32603 | -32008 | -32007 | -32006 | -32005 | -32004 | -32003 | -32002 | -32001 | |
messagerequired | string | length 1–4096 |
data | object | |
retryablerequired | boolean |
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
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
Mirrored byte-for-byte from hyprune/schema at 34849da45183 (2026-10-15). SHA-256 2ffc756163665b449c6e35f09e034ca8c30ca69aaceaeaa9f44aeca1eade7399.