{"id":14967142,"url":"https://github.com/golemfactory/ya-runtime-sdk","last_synced_at":"2025-10-19T09:31:38.252Z","repository":{"id":38836815,"uuid":"364355526","full_name":"golemfactory/ya-runtime-sdk","owner":"golemfactory","description":"Rust library for building new computation environments and self-contained runtimes for yagna","archived":false,"fork":false,"pushed_at":"2023-06-05T08:16:18.000Z","size":133,"stargazers_count":2,"open_issues_count":2,"forks_count":3,"subscribers_count":11,"default_branch":"main","last_synced_at":"2024-10-01T04:29:43.937Z","etag":null,"topics":["golem","ya-runtime"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/golemfactory.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-04T18:50:38.000Z","updated_at":"2023-09-08T18:21:51.000Z","dependencies_parsed_at":"2023-01-22T13:46:07.763Z","dependency_job_id":null,"html_url":"https://github.com/golemfactory/ya-runtime-sdk","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/golemfactory%2Fya-runtime-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/golemfactory%2Fya-runtime-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/golemfactory%2Fya-runtime-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/golemfactory%2Fya-runtime-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/golemfactory","download_url":"https://codeload.github.com/golemfactory/ya-runtime-sdk/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219869245,"owners_count":16555571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["golem","ya-runtime"],"created_at":"2024-09-24T13:37:31.158Z","updated_at":"2025-10-19T09:31:32.953Z","avatar_url":"https://github.com/golemfactory.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ya-runtime-sdk\n\n`ya-runtime-sdk` is a Rust library for building Computation Environments and Self-contained Runtimes, \nexecuted by Provider nodes in the Golem network.\n\n`ya-runtime-sdk` provides facilitation in the following areas:\n\n- interfacing with the computation orchestrator\n- computation lifecycle management\n- command output handling\n- billing information reporting (TBD)\n\n---\n\nTable of contents\n- [Runtime overview](#runtime-overview)\n  - [Runtime orchestration](#runtime-orchestration)\n    - [Runtime execution mode](#runtime-execution-mode)\n    - [Command execution mode](#command-execution-mode)\n  - [Complementary functions](#complementary-functions)\n  - [Events](#events)\n- [Implementation](#implementation)\n  - [Context](#context)\n  - [Configuration](#configuration)\n- [Debugging](#debugging)\n- [Deploying](#deploying)\n\n---\n\n## Runtime overview\n\nRuntime is responsible for performing computation specified in an Agreement between a Provider and a \nRequestor. Runtimes are executed only after a successful marketplace negotiation has taken place, where prices, \ncomputation deadlines and rented hardware resources have been agreed upon.\n\nThe degree of remote control that a Requestor can have over a Runtime depends on its flavour:\n\n1. Computation Environment\n   \n   Fully controlled by the Requestor via a well-defined set of commands (\"ExeScript\"). \n   Requestor is responsible for triggering deployment of the payload (e.g. a Virtual Machine image) \n   specified in an Agreement, starting the environment, executing commands within that environment \n   and terminating the setup.\n\n\n2. Self-contained Runtime\n   \n   The payload is pre-defined by the developer. In this case, deploying, starting, executing\n   commands and terminating the runtime can be only hinted by the Requestor; the implementation determines the exact \n   behaviour of those actions.\n    \n\n### Runtime orchestration\n\nRuntimes are orchestrated by their parent process, the ExeUnit Supervisor, via a standardized set of command line \narguments and a Runtime API protocol. `ya-runtime-sdk` handles all the communication automatically for any struct \nimplementing the `Runtime` trait.\n\nThe `Runtime` trait specifies handlers for each of the execution phases:\n\n- `deploy`\n\n  **Description:** Initial configuration of the environment and payload.\n  \n  **Output:** Optional JSON response in the following format:\n  ```json \n  {\n      \"startMode\": \"blocking\",\n      \"valid\": {\"Ok\": \"success\"},\n      \"vols\": [\n          {\"name\": \"vol-9a0c1c4a\", \"path\": \"/in\"},\n          {\"name\": \"vol-a68672e0\", \"path\": \"/out\"}\n      ],\n      \"customKey\": \"customValue\"\n  }\n  ```\n\n  **Required properties**:\n  - `startMode`\n    \n    Determines whether a runtime is a long-running application or a one-shot command.\n    - `\"blocking\"` for `RuntimeMode::Server`\n    - `\"empty\"` for `RuntimeMode::Command`\n  \n  - `valid`\n    \n    Deployment status.\n    - `{\"Ok\": \"success message\"}`\n    - `{\"Err\": \"error message\"}`\n  \n  - `vols`\n    \n    Local filesystem directory to runtime directory mapping.\n    - `name` is a subdirectory on a local filesystem, in a directory chosen by the Supervisor,\n    - `path` is an alias of that directory, seen from inside the runtime and Supervisor services (e.g. file transfer)\n    \n- `start`\n\n  **Description:** Enable the runtime to be used by the Requestor.\n\n  Can be run in **one** of the [execution modes](#runtime-execution-mode).\n  \n  **Output:** Optional JSON response.\n\n- `run_command`\n\n  **Description:** Parse, interpret and handle an array of string arguments. Optional in case of self-contained runtimes.\n\n  Can be run in **any** of the [execution modes](#command-execution-mode)\n  \n- `kill_command`\n\n  **Description:** Terminate command execution.\n\n  Optional in case of self-contained runtimes.\n\n- `stop`\n\n  **Description:** Terminate the runtime.\n\n  May be triggered by the Requestor on demand or by the Provider Agent due to execution time constraints\n  specified in the Agreement. Runtime is given a short (\u003c 5s) time window to perform a graceful shutdown, otherwise\n  it will be forcefully closed.\n\n#### Runtime execution mode\n\n`Runtime::MODE` specifies one of 2 possible execution modes:\n\n- `Server`\n\n  The `start` command spawns a background task and returns promptly. Usually, `run` commands have to be invoked \n  in `Server` mode (see [command execution modes](#command-execution-mode)).\n\n\n- `Command`\n\n  `start` command is a one-shot invocation, which completes promptly. All of the `run` commands are expected to be invoked\n  via command line.\n\n#### Command execution mode\n\n- `Server`\n\n  Command was invoked by a runtime running in a `Server` mode.\n\n  Developers may use the `RunCommandExt` trait or `Context::command` to wrap command execution and publish  \n  stdout, stderr and usage counter events in a simple manner.  \n\n- `Command`\n\n  Command was invoked via command line.\n\n`run_command` implementation should distinguish each of the execution modes but is not required to support both.\n\n### Complementary functions\n\nIn addition to the lifecycle and execution logic, runtimes can implement 2 additional customization functions:\n\n- `test`\n\n  **Description:** Perform a self-test. \n  \n  Always executed during Provider Agent startup - i.e. during local yagna provider initialization,\n  external to the negotiation phase and computation.\n\n  Implementation must allow execution at any time.\n\n  **Example:** the VM runtime (`ya-runtime-vm`) spawns a Virtual Machine with a minimal test image attached, to verify that\n  KVM is properly configured on provider's operating system and all bundled components are available in the expected\n  location on disk.\n\n- `offer`\n\n  **Description:** Inject custom properties and / or constraints to an Offer, published by the Provider Agent on the marketplace. `offer`\n  is executed by the Provider Agent while publishing new offers on the market, also during agent's initialization phase.\n\n  Implementation must allow execution at any time.\n\n  **Output:** Optional JSON response in the following format:\n\n  ```json \n  {\n      \"constraints\": \"\",\n      \"properties\": {}\n  }\n  ```\n\n### Events\n\n(TBD) Future versions of `ya-runtime-sdk` may cover additional types of events:\n\n- runtime state change indication w/ JSON payload\n- custom usage counters for billing purposes\n\n---\n\n## Implementation\n\nRuntimes can be implemented by performing the following steps:\n\n  - `#[derive(Default, RuntimeDef)]` on a runtime struct\n  - implement the `Runtime` trait for the struct\n  - use the `ya_runtime_sdk::run` method to start the runtime\n\nSee the [`example-runtime`](examples/example-runtime) for more details.\n\n### Context\n\nEach of the `Runtime` trait functions is parameterized with a mutable reference to the runtime, and a runtime\nexecution context object.\n\nThe `Context` struct exposes the following properties:\n\n- `cli`\n\n  Command line arguments provided to the binary\n\n- `conf`\n\n  Deserialized runtime configuration\n\n- `conf_path`\n\n  Path to the configuration file on a local filesystem\n\n- `env`\n\n  An object implementing the `Env` (environment settings) trait\n\n- `emitter`\n\n  Command event emitter\n\n`Context` also exposes functions for configuration persistence:\n\n- `read_config`\n\n  Read configuration from the specified path. Supports `JSON` (default), `YAML` and `TOML` file formats.\n  The desired format is \n\n- `write_config`\n\n  Write configuration to the specified path.\n\n- `control`\n\n  Return a runtime control object. Its `shutdown` method allows to terminate the runtime running in Server mode.\n\n### Configuration\n\nConfiguration struct can be set via a `#[conf(..)]` attribute of the `RuntimeDef` derive macro. On runtime startup, \nconfiguration is read from a file located at `~/.local/share/\u003ccrate_name\u003e/\u003ccrate_name\u003e.\u003cformat\u003e`.\n\n## Debugging\n\nDevelopers can use the [ya-runtime-dbg](https://github.com/golemfactory/ya-runtime-dbg) tool to interact with a runtime\nrunning in `Server` mode. See the `README.md` file in the linked repository for more details.\n\n## Deploying\n\n1. Create a `ya-runtime-\u003cruntime_name\u003e.json` descriptor file in the **plugins directory**.\n\n```json\n  [\n    {\n      \"name\": \"\u003cruntime_name\u003e\",\n      \"version\": \"0.1.0\",\n      \"supervisor-path\": \"exe-unit\",\n      \"runtime-path\": \"\u003cruntime_dir\u003e/\u003cruntime_bin\u003e\",\n      \"description\": \"Custom runtime \",\n      \"extra-args\": [\"--runtime-managed-image\"]\n    }\n  ]\n```\n\n2. Edit `~/.local/share/ya-provider/presets.json`:\n    \n    - create a `presets` entry for `exeunit-name: \"\u003cruntime_name\u003e\"` (e.g. copy an existing preset)\n    - include the preset name in `active` array\n\n3. Start `golemsp` or `ya-provider`.\n\nThe **plugins directory** is by default located at:\n\n  - golemsp: `~/.local/lib/yagna/plugins/`\n  - ya-provider: `/usr/lib/yagna/plugins/`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgolemfactory%2Fya-runtime-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgolemfactory%2Fya-runtime-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgolemfactory%2Fya-runtime-sdk/lists"}