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.
Raw schema
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.hellosession.pingstate.subscribestate.snapshotstate.unsubscribeworld.loadsurface.focusmovement.setshell.claimshell.releaseshell.overlayruntime.exit
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.1" | |
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")[] | items ≥ 0 · unique items |
eventsrequired | ("state.delta" | "runtime.notice" | "session.revoked")[] | 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 |
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 |
runtime.notice#
params · object
| Field | Type | Constraints |
|---|---|---|
levelrequired | "info" | "warning" | "error" | |
coderequired | string | length 1–256 |
messagerequired | string | length 1–4096 |
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 |
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
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
Examples
Offline fixtures from the schema repository, validated by its test suite. They show shape, not a real session or package.
ipc/error.json
{ "jsonrpc": "2.0", "id": "1", "error": { "code": -32002, "message": "Capability denied.", "data": { "retryable": false } }}ipc/movement.set.request.json
{ "jsonrpc": "2.0", "id": "8", "method": "movement.set", "params": { "modeId": "com.hyprune.fly" }}ipc/movement.set.response.json
{ "jsonrpc": "2.0", "id": "8", "result": { "revision": 1 }}ipc/runtime.exit.request.json
{ "jsonrpc": "2.0", "id": "12", "method": "runtime.exit", "params": {}}ipc/runtime.exit.response.json
{ "jsonrpc": "2.0", "id": "12", "result": { "revision": 1 }}ipc/runtime.notice.notification.json
{ "jsonrpc": "2.0", "method": "runtime.notice", "params": { "level": "info", "code": "world.ready", "message": "World ready." }}ipc/session.hello.request.json
{ "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.json
{ "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.json
{ "jsonrpc": "2.0", "id": "2", "method": "session.ping", "params": {}}ipc/session.ping.response.json
{ "jsonrpc": "2.0", "id": "2", "result": { "monotonicMs": 1000 }}ipc/session.revoked.notification.json
{ "jsonrpc": "2.0", "method": "session.revoked", "params": { "reason": "Grant revoked." }}ipc/shell.claim.request.json
{ "jsonrpc": "2.0", "id": "9", "method": "shell.claim", "params": { "outputs": [ "output-1" ] }}ipc/shell.claim.response.json
{ "jsonrpc": "2.0", "id": "9", "result": { "leaseId": "lease-1", "revision": 1 }}ipc/shell.overlay.request.json
{ "jsonrpc": "2.0", "id": "11", "method": "shell.overlay", "params": { "leaseId": "lease-1", "outputId": "output-1", "visible": true, "exclusiveInput": true }}ipc/shell.overlay.response.json
{ "jsonrpc": "2.0", "id": "11", "result": { "revision": 1 }}ipc/shell.release.request.json
{ "jsonrpc": "2.0", "id": "10", "method": "shell.release", "params": { "leaseId": "lease-1" }}ipc/shell.release.response.json
{ "jsonrpc": "2.0", "id": "10", "result": { "revision": 1 }}ipc/state.delta.notification.json
{ "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.json
{ "jsonrpc": "2.0", "id": "4", "method": "state.snapshot", "params": { "subscriptionId": "sub-1" }}ipc/state.snapshot.response.json
{ "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.json
{ "jsonrpc": "2.0", "id": "3", "method": "state.subscribe", "params": { "topics": [ "state" ] }}ipc/state.subscribe.response.json
{ "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.json
{ "jsonrpc": "2.0", "id": "5", "method": "state.unsubscribe", "params": { "subscriptionId": "sub-1" }}ipc/state.unsubscribe.response.json
{ "jsonrpc": "2.0", "id": "5", "result": { "ok": true }}ipc/surface.focus.request.json
{ "jsonrpc": "2.0", "id": "7", "method": "surface.focus", "params": { "surfaceId": "surface-1", "intent": "pointer" }}ipc/surface.focus.response.json
{ "jsonrpc": "2.0", "id": "7", "result": { "revision": 1 }}ipc/world.load.request.json
{ "jsonrpc": "2.0", "id": "6", "method": "world.load", "params": { "worldId": "com.hyprune.observatory", "spawnId": "arrival" }}ipc/world.load.response.json
{ "jsonrpc": "2.0", "id": "6", "result": { "revision": 1 }}Mirrored byte-for-byte from hyprune/schema at 34849da45183 (2026-10-15). SHA-256 982df2596d2ae688a1572456330146dc5701e6b7a3571b16cbdeca470dea535f.