{"id":50672933,"url":"https://github.com/khalidsaidi/relayorb","last_synced_at":"2026-06-08T13:02:22.431Z","repository":{"id":360597354,"uuid":"1128172424","full_name":"khalidsaidi/relayorb","owner":"khalidsaidi","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-27T05:25:41.000Z","size":107618,"stargazers_count":2,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-27T05:26:50.548Z","etag":null,"topics":["ai-agents","cloud-run","control-plane","gcp","observability","platform-engineering","relayorb","terraform","tool-routing"],"latest_commit_sha":null,"homepage":"https://relayorb.com","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/khalidsaidi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-05T08:46:03.000Z","updated_at":"2026-05-27T05:14:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/khalidsaidi/relayorb","commit_stats":null,"previous_names":["khalidsaidi/relayorb"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/khalidsaidi/relayorb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khalidsaidi%2Frelayorb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khalidsaidi%2Frelayorb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khalidsaidi%2Frelayorb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khalidsaidi%2Frelayorb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/khalidsaidi","download_url":"https://codeload.github.com/khalidsaidi/relayorb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/khalidsaidi%2Frelayorb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34063159,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["ai-agents","cloud-run","control-plane","gcp","observability","platform-engineering","relayorb","terraform","tool-routing"],"created_at":"2026-06-08T13:02:21.733Z","updated_at":"2026-06-08T13:02:22.426Z","avatar_url":"https://github.com/khalidsaidi.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RelayOrb\n\n[![Terraform Registry Modules Smoke](https://github.com/khalidsaidi/relayorb/actions/workflows/terraform-registry-modules-smoke.yml/badge.svg)](https://github.com/khalidsaidi/relayorb/actions/workflows/terraform-registry-modules-smoke.yml)\n\n## Website\n\n- Website: https://relayorb.com\n- Try demo: https://relayorb.com/demo\n- Docs: https://relayorb.com (primary overview) + GitHub docs (canonical runbooks/implementation)\n- Production reliability: https://relayorb.com/reliability\n- Real-world cost profile: https://relayorb.com/cost_profile.json\n- Terraform modules:\n  - https://registry.terraform.io/modules/khalidsaidi/relayorb/google/latest\n  - https://registry.terraform.io/modules/khalidsaidi/relayorb-demo/google/latest\n\nrelayorb.com is the front door; GitHub remains the canonical source of truth for implementation details and runbooks.\n\nGitHub metadata status:\n- Homepage URL and discovery topics are configured.\n- Social preview image should be managed in GitHub repo settings (use the site OG artwork).\n\nRelayOrb is a capability gateway for AI agents. It enforces auth and policy, routes to healthy workers via a registry, validates schemas end-to-end, and records deterministic invocation artifacts with request-id idempotency and replay.\n\nGateway also supports asynchronous execution via `POST /v1/submit` and `GET /v1/jobs/:jobId`.\n\n## Production reliability\n\nRelayOrb has been deployed continuously in production since February 2026. The public reliability report publishes 30 days of Cloud Monitoring and Cloud Logging data from the live control plane:\n\n- Reliability report: https://relayorb.com/reliability\n- Stats JSON: https://relayorb.com/stats.json\n\nThe traffic in that report is synthetic monitoring and control-plane traffic, not public user adoption. External invoke counters remain honest at zero.\n\n## Real-world cost profile\n\nRelayOrb also publishes the live Cloud Run cost lesson from operating the control plane:\n\n- Cost profile JSON: https://relayorb.com/cost_profile.json\n\nThe cost profile is modeled from Cloud Monitoring billable instance time and public Cloud Billing SKU prices for `us-central1`. It shows the difference between the previous always-warm deployment and the current `minScale=0` posture.\n\n## Project Surfaces\n\n- Open-source core: runtime, SDK, conformance tooling, and docs in this repository.\n- Reference deployment: Terraform and workflows for GCP rollout.\n- Demo posture: self-hosted anonymous showcase environment with LB-only access and private internals.\n\n## Demo Posture\n\nRelayOrb includes a demo posture (no login/API key) with strict safety limits for self-hosted evaluation.\n\nThe hosted anonymous demo has been retired. To run the same posture yourself:\n\n```bash\nexport RELAYORB_DEMO_URL=\"https://YOUR-DEMO-URL\"\n```\n\nInvoke `rag.search@v1`:\n\n```bash\ncurl -sS -X POST \"$RELAYORB_DEMO_URL/v1/invoke\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\n    \"requestId\":\"demo-req-1\",\n    \"caller\":{\"agentId\":\"anonymous\",\"role\":\"anonymous\"},\n    \"capability\":\"rag.search@v1\",\n    \"payload\":{\"query\":\"what is relayorb?\",\"topK\":3}\n  }' | jq\n```\n\nForbidden capability example (expected `403`):\n\n```bash\ncurl -sS -X POST \"$RELAYORB_DEMO_URL/v1/invoke\" \\\n  -H \"content-type: application/json\" \\\n  -d '{\n    \"requestId\":\"demo-req-forbidden\",\n    \"caller\":{\"agentId\":\"anonymous\",\"role\":\"anonymous\"},\n    \"capability\":\"sql.query@v1\",\n    \"payload\":{\"sql\":\"select 1\"}\n  }' | jq\n```\n\nDemo details and limits: [docs/DEMO.md](/home/khalid/relayorb/docs/DEMO.md)\n\n## Components\n\n- `relayorb-gateway`: invoke entrypoint, policy, routing, artifact recording\n- `relayorb-registry`: capability registry + TTL heartbeats\n- `relayorb-worker-sdk`: worker server wrapper and heartbeat client\n- `relayorb-policy`: RBAC/ABAC-lite rules and budget limiter\n- `worker-mock-rag`: sample capability provider (`rag.search@v1`)\n- `agent-client`: sample CLI invoker\n\n## Run Locally\n\n1. Start stack:\n```bash\ncd ops\ndocker compose up --build\n```\n\nOptional: enable zero-cost live search results instead of mock responses:\n```bash\ncd ops\nRAG_LIVE_SEARCH=1 docker compose up --build\n```\n\n2. Invoke sample capability:\n```bash\ncd ..\ncargo run -p agent-client -- rag.search@v1 '{\"query\":\"earnings guidance\",\"topK\":3}'\n```\n\n3. Replay stored invocation:\n```bash\ncurl http://127.0.0.1:8080/v1/replay/\u003crequest-id\u003e\n```\n\n4. Run one-command local full-surface proof (invoke/replay/submit/jobs/authz/metrics):\n```bash\nbash ops/smoke/local-full-surface-proof.sh\n```\n\n5. Run a business-readable real-world showcase (batch research, async job, RBAC, replay):\n```bash\nbash ops/smoke/real-world-showcase.sh\n```\n\n6. Optional ephemeral cloud demo proof with automatic destroy:\n```bash\nTF_BACKEND_BUCKET=\u003cdemo-tfstate-bucket\u003e \\\nTF_VARS_FILE=infra/gcp/terraform/envs/demo/terraform.tfvars \\\nbash ops/smoke/ephemeral-demo-proof.sh\n```\n\n## Deploy with Terraform\n\nRelayOrb publishes two Terraform Registry modules:\n\n- Prod-oriented module (OIDC-first): `khalidsaidi/relayorb/google`  \n  https://registry.terraform.io/modules/khalidsaidi/relayorb/google/latest\n- Anonymous demo module (LB-only gateway posture): `khalidsaidi/relayorb-demo/google`  \n  https://registry.terraform.io/modules/khalidsaidi/relayorb-demo/google/latest\n\nExample (prod):\n\n```hcl\nmodule \"relayorb\" {\n  source  = \"khalidsaidi/relayorb/google\"\n  version = \"0.1.1\"\n\n  project_id     = \"relayorb-prod\"\n  gateway_image  = \"ghcr.io/khalidsaidi/relayorb-gateway:v0.1.1\"\n  registry_image = \"ghcr.io/khalidsaidi/relayorb-registry:v0.1.1\"\n  worker_image   = \"ghcr.io/khalidsaidi/relayorb-rag:v0.1.1\"\n  scraper_image  = \"ghcr.io/khalidsaidi/relayorb-metrics-scraper:v0.1.1\"\n}\n```\n\nExample (demo):\n\n```hcl\nmodule \"relayorb_demo\" {\n  source  = \"khalidsaidi/relayorb-demo/google\"\n  version = \"0.1.0\"\n\n  project_id     = \"relayorb-demo\"\n  gateway_image  = \"ghcr.io/khalidsaidi/relayorb-gateway:v0.1.1\"\n  registry_image = \"ghcr.io/khalidsaidi/relayorb-registry:v0.1.1\"\n  worker_image   = \"ghcr.io/khalidsaidi/relayorb-rag:v0.1.1\"\n  scraper_image  = \"ghcr.io/khalidsaidi/relayorb-metrics-scraper:v0.1.1\"\n}\n```\n\nReference Terraform configs also remain in this repo for direct use/customization:\n- Core Terraform: `infra/gcp/terraform/`\n- Anonymous demo env: `infra/gcp/terraform/envs/demo/`\n- Demo deploy workflow: `.github/workflows/deploy-demo.yml`\n\nFor reproducibility with in-repo Terraform, pin to a Git tag/commit before applying.\n\n## Write a Capability Worker\n\n1. Define manifest with `capabilityId`, schemas, limits, and routing hints.\n2. Implement `CapabilityHandler` in an SDK-based worker.\n3. Register worker capabilities on startup and send heartbeats.\n4. Add policy rule allowing target role/capability/sideEffects.\n\n## Verify Conformance\n\nOffline validation:\n```bash\ncargo run -p relayorb-conformance -- validate \\\n  --manifest conformance/manifests/rag.search@v1.json \\\n  --vectors conformance/vectors/rag.search@v1.json\n```\n\nLive runtime validation (worker target):\n```bash\ncargo run -p relayorb-conformance -- run \\\n  --target worker \\\n  --base-url http://127.0.0.1:8090 \\\n  --manifest conformance/manifests/rag.search@v1.json \\\n  --vectors conformance/vectors/rag.search@v1.json\n```\n\n## Configuration\n\nBase config is `config/dev.toml`, overridden by env vars:\n- `RELAYORB_ENV`\n- `RELAYORB_REGION`\n- `RELAYORB_SERVICE_NAME`\n- `REGISTRY_URL`\n- `DATABASE_URL`\n- `AUTH_MODE` (`hmac` or `oidc`)\n- `ALLOW_HMAC_IN_PROD` (`true` required to permit HMAC when `RELAYORB_ENV=prod`)\n- `SECRET_AUTH_HMAC` (dev / explicit hmac mode)\n- `OIDC_ISSUER` (prod oidc mode)\n- `OIDC_AUDIENCE` (prod oidc mode)\n- `JWKS_URL` (prod oidc mode)\n- `AUTH_CLOCK_SKEW_SECONDS` (optional, default `120`)\n- `JWKS_REFRESH_INTERVAL_SECONDS` (optional, default `300`)\n- `INTERNAL_IAM_AUTH` (`on|off|auto`, default `auto`; in prod this enables Cloud Run IAM auth for internal service calls)\n- `OTEL_EXPORTER_OTLP_ENDPOINT` (optional)\n- `RELAYORB_METRICS_EXPORTER` (`prometheus` by default; set `none` to disable `/metrics`)\n- `METRICS_AUTH_MODE` (`public` or `bearer`; defaults to `bearer` in prod/demo and `public` elsewhere)\n- `METRICS_BEARER_TOKEN` (required when `METRICS_AUTH_MODE=bearer`)\n- `REGISTRY_OWNERSHIP_POLICY_PATH` (optional, default `config/registry-ownership.toml`)\n- `REGISTRY_WORKER_AUTH_MODE` (`disabled` or `oidc`; optional for registry)\n- `REGISTRY_WORKER_OIDC_ISSUER` (registry worker auth, default `https://accounts.google.com`)\n- `REGISTRY_WORKER_OIDC_AUDIENCE` (required when registry worker auth mode is `oidc`)\n- `REGISTRY_WORKER_JWKS_URL` (registry worker auth, default Google JWKS URL)\n- `REGISTRY_WORKER_AUTH_CLOCK_SKEW_SECONDS` (optional for registry worker auth)\n- `REGISTRY_WORKER_JWKS_REFRESH_INTERVAL_SECONDS` (optional for registry worker auth)\n\n## Service naming model\n\nCloud Run services follow `relayorb-\u003ccomponent\u003e-\u003cenv\u003e`, for example:\n- `relayorb-gateway-prod`\n- `relayorb-registry-prod`\n- `relayorb-rag-prod`\n\nWorkers should set:\n- `RELAYORB_ENV`\n- `RELAYORB_SERVICE_NAME`\n- `REGISTRY_URL`\n- `RELAYORB_PUBLIC_BASE_URL` (or `WORKER_BASE_URL` alias)\n- `REGISTRY_IDENTITY_AUDIENCE` (required when registry enforces worker OIDC identity)\n\nProduction network posture:\n- Gateway stays public (OIDC-protected at app layer).\n- Registry and workers are private (Cloud Run IAM invoker check + scoped `roles/run.invoker` bindings).\n- Internal calls use `X-Serverless-Authorization: Bearer \u003cid_token\u003e` with audience set to the target service run.app URL.\n\n## Observability\n\n- Tracing:\n  - JSON structured logs on all services.\n  - Optional OTEL export when `OTEL_EXPORTER_OTLP_ENDPOINT` is set.\n  - Trace propagation headers: `x-trace-id` and `traceparent`.\n- Metrics:\n  - Prometheus endpoint on each service:\n    - gateway: `GET /metrics` on port `8080`\n    - registry: `GET /metrics` on port `8081`\n    - worker: `GET /metrics` on port `8090`\n- In prod/demo, `/metrics` is bearer-protected (`METRICS_AUTH_MODE=bearer`).\n  - `relayorb-metrics-scraper-prod` uses an IAM-aware local proxy so each scrape request carries both:\n    - `X-Serverless-Authorization` (Cloud Run IAM ID token)\n    - `Authorization` (metrics bearer token)\n  - Scraped series are exported to Cloud Monitoring as `prometheus.googleapis.com/*`.\n  - All service metrics include the base labels:\n    - `env`, `service_name`, `version`, `region`\n  - Capability/request series also include controlled labels:\n    - `capability_id`, `result`, `error_code` (where applicable)\n  - Core operational series:\n    - `relayorb_gateway_invoke_latency_ms`\n    - `relayorb_gateway_invoke_requests_total`\n    - `relayorb_gateway_idempotency_replays_total`\n    - `relayorb_gateway_jobs_queued`\n    - `relayorb_registry_register_requests_total`\n    - `relayorb_registry_heartbeat_requests_total`\n    - `relayorb_worker_invoke_latency_ms`\n\n## Security\n\n- No secrets are committed.\n- Use Secret Manager for credentials.\n- Every response includes `requestId` and `traceId`.\n- Async job status reads are creator-or-admin (`GET /v1/jobs/:jobId`).\n- Registry governance smoke can be run manually:\n  - `bash ops/smoke/registry-governance-smoke.sh \u003cregistry-url\u003e`\n\n## Project Governance\n\n- License: [LICENSE](/home/khalid/relayorb/LICENSE)\n- Security reporting: [SECURITY.md](/home/khalid/relayorb/SECURITY.md)\n- Contribution guide: [CONTRIBUTING.md](/home/khalid/relayorb/CONTRIBUTING.md)\n- Code of conduct: [CODE_OF_CONDUCT.md](/home/khalid/relayorb/CODE_OF_CONDUCT.md)\n- Roadmap: [ROADMAP.md](/home/khalid/relayorb/docs/ROADMAP.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhalidsaidi%2Frelayorb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkhalidsaidi%2Frelayorb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkhalidsaidi%2Frelayorb/lists"}