start-os/container-runtime/RPCSpec.md

Container RPC Server Specification

The container runtime exposes a JSON-RPC server over a Unix socket at /media/startos/rpc/service.sock.

Methods

init

Initialize the runtime and system.

params

{
  id: string,
  kind: "install" | "update" | "restore" | null,
}

response

null

exit

Shutdown runtime and optionally run exit hooks for a target version.

params

{
  id: string,
  target: string | null,  // ExtendedVersion or VersionRange
}

response

null

start

Run main method if not already running.

params

None

response

null

stop

Stop main method by sending SIGTERM to child processes, and SIGKILL after timeout.

params

None

response

null

execute

Run a specific package procedure.

params

{
  id: string,           // event ID
  procedure: string,    // JSON path (e.g., "/backup/create", "/actions/{name}/run")
  input: any,
  timeout: number | null,
}

response

any

sandbox

Run a specific package procedure in sandbox mode. Same interface as execute.

UNIMPLEMENTED: this feature is planned but does not exist

params

{
  id: string,
  procedure: string,
  input: any,
  timeout: number | null,
}

response

any

callback

Handle a callback from an effect.

params

{
  id: number,
  args: any[],
}

response

null (no response sent)

eval

Evaluate a script in the runtime context. Used for debugging.

params

{
  script: string,
}

response

any

Procedures

The execute and sandbox methods route to procedures based on the procedure path:

Procedure	Description
/backup/create	Create a backup
/actions/{name}/getInput	Get input spec for an action
/actions/{name}/run	Run an action with input