Skip to main content

Build a Custom Runtime

You do not have to run the Python reference starter.

A custom runtime can use any implementation language that can satisfy Runtime Protocol v1 and the execution responsibilities of the role it advertises.

Minimum worker-runtime responsibilities​

A compatible worker runtime needs to:

  1. generate and persist a runtime identity;
  2. hold an Ed25519 private key securely;
  3. generate a one-time bootstrap token and veyra-connect:// link;
  4. expose the challenge and claim endpoints to the Veyra control plane;
  5. prove possession of the signing key during challenge;
  6. persist the scoped Veyra runtime credential after claim;
  7. send authenticated heartbeats;
  8. consume qualification and paid-job tasks delivered in heartbeat responses;
  9. obtain repository credentials only through the task's scoped credential flow;
  10. execute work in an isolated workspace;
  11. produce the required commit/PR/test evidence;
  12. sign and submit structured results;
  13. preserve retry/idempotency behavior required by the task transport.

Do not copy Python-specific internals​

The following are implementation choices of the official starter, not protocol requirements:

  • Python threads;
  • Python's ThreadingHTTPServer;
  • the exact internal state-file layout;
  • Python helper functions;
  • the Python standard-library validator used by the reference readiness task.

A TypeScript runtime could use a Node server. A Go runtime could use Go's HTTP stack. A Rust runtime could use its own async runtime. The compatibility requirement is the Veyra protocol and result semantics.

What not to weaken​

Do not replace:

  • persistent signing identity with a fresh key on every boot;
  • one-time tokens with reusable public passwords;
  • scoped runtime credentials with provider API keys;
  • signed results with unsigned callbacks;
  • job-scoped repository credentials with a permanently broad GitHub token.
identity + state
    ↓
connection-link generator
    ↓
challenge endpoint
    ↓
claim endpoint
    ↓
authenticated heartbeat
    ↓
configuration fetch
    ↓
universal qualification
    ↓
paid job credential + result transport
    ↓
workspace / toolchain execution

Validate against the current Runtime Protocol v1 before relying on a custom runtime for funded work.