Skip to main content
Device RPC lets you call typed methods on services running on your edge device — from the Golain cloud, using normal HTTP requests with JSON bodies. You write real gRPC handlers on the device; Golain handles authentication, routing, and JSON conversion so your app does not need gRPC or MQTT libraries. This is different from legacy shell RPC, which runs allowlisted shell commands over signed control topics (exec:<command>). Device RPC is for protobuf services with a discoverable schema, audit trails, and typed request/response shapes.

​
Who this is for

​
At a glance

​
Core concepts

Schema

When your device connects, Golain learns which gRPC services and methods it exposes. You can list them from the management API — no manual proto upload.

Unary invoke

Call a method synchronously: POST JSON to the RPC host (https://rpc.ilyama.golain.io) with {Service}/{Method} in the URL. Golain delivers the call to the device and returns Connect JSON.

Server stream

Stream server-streaming methods over SSE: POST to https://rpc.ilyama.golain.io/.../streams/{Service}/{Method} with Accept: text/event-stream. Each event carries a base64 protobuf message.

Queued invoke

Enqueue a unary call when the device may be offline. Poll until the call succeeds. Delivery is at-least-once — design handlers to be safe on retry.

​
Prerequisites

Before you invoke methods from the cloud, confirm:
  1. Device registered in the Console or via platform-tui — you need the device UUID.
  2. Omega with device-rpc enabled and deployed on the device — see Omega setup.
  3. Device online on MQTT so Golain can learn its service schema.
  4. Caller permission — your user needs can_invoke_rpc on the target device.
Invoke, stream, and enqueue requests go to the RPC host (https://rpc.ilyama.golain.io) — paths like /projects/.../devices/... with no /core/api/v1 prefix. Management routes (list services, reflect, audit) use https://api.ilyama.golain.io/core/api/v1/....
Device RPC is separate from legacy shell RPC. Use Device RPC when you need typed protobuf services; use shell RPC for simple command execution.

​
Typical first-time flow

  1. Enable device-rpc in Omega and deploy the device → Omega setup.
  2. Confirm services — list available methods via the management API (for example golain.device.v1.EchoService / Echo).
  3. Invoke a method — POST JSON to the RPC host → Invoking methods. For server-streaming methods, use the /streams/ path. For offline-tolerant delivery, use Queued invoke.
  4. Review audit — optional ?session_id= on invoke groups traces you can query later.

​
Next steps