Skip to content

IPC protocol 0.1

Schema reference / IPC protocol / 0.1

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 v0 ipc”
Dialect
JSON Schema 2020-12 · unknown fields rejected unless marked
Raw schemaipc.schema.json · 1,725 lines · 40 KB
DownloadOpen rawsha256 982df2596d2a…
Loading ipc.schema.json…

This is the first published version of this contract.

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.1"
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")[]items ≥ 0 · unique items
eventsrequired("state.delta" | "runtime.notice" | "session.revoked")[]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

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

runtime.notice#

params · object

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

session.revoked#

params · object

FieldTypeConstraints
reasonrequiredstringlength 1–4096

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

snapshot#

object

FieldTypeConstraints
sessionIdrequiredstringlength 1–128
revisionrequiredrevision
staterequiredstate

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

Examples

Offline fixtures from the schema repository, validated by its test suite. They show shape, not a real session or package.

ipc/error.jsonerror.json · 11 lines · 156 B
{
"jsonrpc": "2.0",
"id": "1",
"error": {
"code": -32002,
"message": "Capability denied.",
"data": {
"retryable": false
}
}
}
ipc/movement.set.request.jsonmovement.set.request.json · 8 lines · 115 B
{
"jsonrpc": "2.0",
"id": "8",
"method": "movement.set",
"params": {
"modeId": "com.hyprune.fly"
}
}
ipc/movement.set.response.jsonmovement.set.response.json · 7 lines · 73 B
{
"jsonrpc": "2.0",
"id": "8",
"result": {
"revision": 1
}
}
ipc/runtime.exit.request.jsonruntime.exit.request.json · 6 lines · 81 B
{
"jsonrpc": "2.0",
"id": "12",
"method": "runtime.exit",
"params": {}
}
ipc/runtime.exit.response.jsonruntime.exit.response.json · 7 lines · 74 B
{
"jsonrpc": "2.0",
"id": "12",
"result": {
"revision": 1
}
}
ipc/runtime.notice.notification.jsonruntime.notice.notification.json · 9 lines · 150 B
{
"jsonrpc": "2.0",
"method": "runtime.notice",
"params": {
"level": "info",
"code": "world.ready",
"message": "World ready."
}
}
ipc/session.hello.request.jsonsession.hello.request.json · 17 lines · 255 B
{
"jsonrpc": "2.0",
"id": "1",
"method": "session.hello",
"params": {
"protocols": [
"0.1"
],
"client": {
"id": "com.hyprune.shell",
"name": "Hyprune shell"
},
"capabilities": [
"state.read"
]
}
}
ipc/session.hello.response.jsonsession.hello.response.json · 23 lines · 391 B
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"protocol": "0.1",
"sessionId": "session-1",
"capabilities": [
"state.read"
],
"methods": [
"session.hello",
"session.ping",
"state.subscribe",
"state.snapshot",
"state.unsubscribe"
],
"events": [
"state.delta",
"runtime.notice",
"session.revoked"
]
}
}
ipc/session.ping.request.jsonsession.ping.request.json · 6 lines · 80 B
{
"jsonrpc": "2.0",
"id": "2",
"method": "session.ping",
"params": {}
}
ipc/session.ping.response.jsonsession.ping.response.json · 7 lines · 79 B
{
"jsonrpc": "2.0",
"id": "2",
"result": {
"monotonicMs": 1000
}
}
ipc/session.revoked.notification.jsonsession.revoked.notification.json · 7 lines · 104 B
{
"jsonrpc": "2.0",
"method": "session.revoked",
"params": {
"reason": "Grant revoked."
}
}
ipc/shell.claim.request.jsonshell.claim.request.json · 10 lines · 122 B
{
"jsonrpc": "2.0",
"id": "9",
"method": "shell.claim",
"params": {
"outputs": [
"output-1"
]
}
}
ipc/shell.claim.response.jsonshell.claim.response.json · 8 lines · 99 B
{
"jsonrpc": "2.0",
"id": "9",
"result": {
"leaseId": "lease-1",
"revision": 1
}
}
ipc/shell.overlay.request.jsonshell.overlay.request.json · 11 lines · 187 B
{
"jsonrpc": "2.0",
"id": "11",
"method": "shell.overlay",
"params": {
"leaseId": "lease-1",
"outputId": "output-1",
"visible": true,
"exclusiveInput": true
}
}
ipc/shell.overlay.response.jsonshell.overlay.response.json · 7 lines · 74 B
{
"jsonrpc": "2.0",
"id": "11",
"result": {
"revision": 1
}
}
ipc/shell.release.request.jsonshell.release.request.json · 8 lines · 110 B
{
"jsonrpc": "2.0",
"id": "10",
"method": "shell.release",
"params": {
"leaseId": "lease-1"
}
}
ipc/shell.release.response.jsonshell.release.response.json · 7 lines · 74 B
{
"jsonrpc": "2.0",
"id": "10",
"result": {
"revision": 1
}
}
ipc/state.delta.notification.jsonstate.delta.notification.json · 18 lines · 298 B
{
"jsonrpc": "2.0",
"method": "state.delta",
"params": {
"subscriptionId": "sub-1",
"sessionId": "session-1",
"baseRevision": 0,
"revision": 1,
"changes": {
"runtime": {
"active": true,
"outputs": [
"output-1"
]
}
}
}
}
ipc/state.snapshot.request.jsonstate.snapshot.request.json · 8 lines · 115 B
{
"jsonrpc": "2.0",
"id": "4",
"method": "state.snapshot",
"params": {
"subscriptionId": "sub-1"
}
}
ipc/state.snapshot.response.jsonstate.snapshot.response.json · 37 lines · 624 B
{
"jsonrpc": "2.0",
"id": "4",
"result": {
"snapshot": {
"sessionId": "session-1",
"revision": 0,
"state": {
"runtime": {
"active": false,
"outputs": [
"output-1"
]
},
"world": null,
"surfaces": [],
"movement": {
"modeId": "com.hyprune.fly",
"position": [
0,
1,
0
],
"orientation": [
0,
0,
0,
1
]
},
"shell": {
"leases": []
}
}
}
}
}
ipc/state.subscribe.request.jsonstate.subscribe.request.json · 10 lines · 122 B
{
"jsonrpc": "2.0",
"id": "3",
"method": "state.subscribe",
"params": {
"topics": [
"state"
]
}
}
ipc/state.subscribe.response.jsonstate.subscribe.response.json · 38 lines · 655 B
{
"jsonrpc": "2.0",
"id": "3",
"result": {
"subscriptionId": "sub-1",
"snapshot": {
"sessionId": "session-1",
"revision": 0,
"state": {
"runtime": {
"active": false,
"outputs": [
"output-1"
]
},
"world": null,
"surfaces": [],
"movement": {
"modeId": "com.hyprune.fly",
"position": [
0,
1,
0
],
"orientation": [
0,
0,
0,
1
]
},
"shell": {
"leases": []
}
}
}
}
}
ipc/state.unsubscribe.request.jsonstate.unsubscribe.request.json · 8 lines · 118 B
{
"jsonrpc": "2.0",
"id": "5",
"method": "state.unsubscribe",
"params": {
"subscriptionId": "sub-1"
}
}
ipc/state.unsubscribe.response.jsonstate.unsubscribe.response.json · 7 lines · 70 B
{
"jsonrpc": "2.0",
"id": "5",
"result": {
"ok": true
}
}
ipc/surface.focus.request.jsonsurface.focus.request.json · 9 lines · 138 B
{
"jsonrpc": "2.0",
"id": "7",
"method": "surface.focus",
"params": {
"surfaceId": "surface-1",
"intent": "pointer"
}
}
ipc/surface.focus.response.jsonsurface.focus.response.json · 7 lines · 73 B
{
"jsonrpc": "2.0",
"id": "7",
"result": {
"revision": 1
}
}
ipc/world.load.request.jsonworld.load.request.json · 9 lines · 148 B
{
"jsonrpc": "2.0",
"id": "6",
"method": "world.load",
"params": {
"worldId": "com.hyprune.observatory",
"spawnId": "arrival"
}
}
ipc/world.load.response.jsonworld.load.response.json · 7 lines · 73 B
{
"jsonrpc": "2.0",
"id": "6",
"result": {
"revision": 1
}
}

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