{"id":47701283,"url":"https://github.com/vilano-ai/runtime","last_synced_at":"2026-04-02T17:16:30.063Z","repository":{"id":345078760,"uuid":"1174684978","full_name":"vilano-ai/runtime","owner":"vilano-ai","description":"Durable runtime for building agent systems.","archived":false,"fork":false,"pushed_at":"2026-03-29T00:05:37.000Z","size":961,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-29T00:56:39.020Z","etag":null,"topics":["agent-runtime","ai-agents","bun","durable-execution","elixir","sqlite","typescript","workflow-engine"],"latest_commit_sha":null,"homepage":"https://runtime.vilano.ai","language":"TypeScript","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/vilano-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"docs/support-matrix.md","governance":null,"roadmap":null,"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-03-06T18:12:45.000Z","updated_at":"2026-03-29T00:05:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vilano-ai/runtime","commit_stats":null,"previous_names":["vilano-ai/runtime"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/vilano-ai/runtime","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vilano-ai%2Fruntime","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vilano-ai%2Fruntime/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vilano-ai%2Fruntime/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vilano-ai%2Fruntime/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vilano-ai","download_url":"https://codeload.github.com/vilano-ai/runtime/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vilano-ai%2Fruntime/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31311266,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["agent-runtime","ai-agents","bun","durable-execution","elixir","sqlite","typescript","workflow-engine"],"created_at":"2026-04-02T17:16:29.113Z","updated_at":"2026-04-02T17:16:30.058Z","avatar_url":"https://github.com/vilano-ai.png","language":"TypeScript","readme":"# Vilano Runtime\n\n[![CI](https://github.com/vilano-ai/runtime/actions/workflows/ci.yml/badge.svg)](https://github.com/vilano-ai/runtime/actions/workflows/ci.yml)\n[![Launch Gate](https://github.com/vilano-ai/runtime/actions/workflows/launch-gate.yml/badge.svg)](https://github.com/vilano-ai/runtime/actions/workflows/launch-gate.yml)\n\nVilano Runtime is a durable runtime for building agent systems.\n\nIt replaces retry-based execution with deterministic replay over durable state, allowing\nworkflows and agents to recover correctly from failure.\n\nIn Vilano Runtime:\n\n- the code reruns\n- the state does not\n\nThe system is built around a BEAM-based kernel for coordination and durability, with\ndisposable TypeScript workers executing agent behavior.\n\nVilano Runtime `0.1` ships a TypeScript-first local runtime with a durable BEAM kernel,\ndisposable JS/TS workers, and an operator CLI.\n\nThe current OSS release path is local-first and single-machine. It is built for agent systems that\nneed:\n\n- durable replay instead of best-effort retries\n- long-lived keyed agents instead of ad hoc background processes\n- supervision, exit relationships, and passivation from the runtime itself\n- explicit waits, signals, pubsub, and child execution\n- subprocess-heavy work with durable artifacts\n- inspectable execution timelines instead of opaque background jobs\n\nVilano Runtime is a `0.x` release with a focused support path and a tested core execution model.\n\n## What It Is\n\nVilano Runtime has three main pieces:\n\n- **BEAM kernel**\n  - durable state, leases, waits, retries, signals, service inboxes, relationship semantics,\n    supervision policy, passivation state, and managed worker supervision\n- **JS/TS workers**\n  - replay workflows and service turns, execute agent behavior, run in-process `step()` logic,\n    run durable subprocesses through `exec()`, and stay disposable underneath the kernel\n- **CLI**\n  - local operator surface for bootstrapping the daemon, registering projects, starting runs,\n    inspecting timelines, and delivering signals\n\nThe simplest mental model is:\n\n- BEAM owns truth and coordination\n- JS/TS owns agent behavior\n- workers are disposable\n- services are durable keyed agents\n- workflows orchestrate and supervise them\n\nFor OSS `0.1`, Vilano Runtime runs as a local daemon with:\n\n- single-machine\n- SQLite-backed\n- loopback-only coordination plane\n- per-runtime access token under `VILANO_HOME`\n\nBy default, installed runtime payloads are intended to live under `~/.vilano/installs`, while\nmutable runtime state lives under `~/.vilano/state`.\n\nVilano Runtime uses a local single-user trust model. See\n[docs/trust-model.md](./docs/trust-model.md) for the canonical runtime posture.\n\nVilano Runtime is released under the [Apache-2.0 License](./LICENSE).\n\n## Current Capabilities\n\n- workflows with replay-from-the-top semantics\n- services that behave like durable keyed agents\n- services with durable inboxes and typed `send` / `ask` / `signal`\n- durable `step`, `exec`, `sleep`, `waitForSignal`, `spawn`, and `connect`\n- durable `monitor`, `link`, `trapExit`, and `nextExit`\n- kernel-owned workflow supervision groups with restart budgets\n- explicit mailbox inspection plus `defer()` / `reject()`\n- bounded service inboxes and overload rejection\n- explicit service passivation / wake-on-message state\n- singleton discovery and supervision-group inspection\n- durable topic pubsub with dedupe and restart persistence\n- kernel-scheduled retries with fixed, linear, or exponential backoff plus jitter\n- cancellation propagation across waits, child runs, service asks, and subprocesses\n- managed-worker hard-stop fallback for timed blocking steps\n- `run inspect` and `run replay` for durable operator visibility\n- `run explain` for quick wait/child-path diagnosis\n- packaged local install flow with immutable runtime payloads under the managed install root\n  and mutable state under `VILANO_HOME`\n\n## Supported Path\n\nVilano Runtime `0.1` ships with:\n\n- BEAM kernel\n- TypeScript SDK\n- Bun CLI\n- Bun managed worker\n- local SQLite-backed runtime home\n\nManaged workers supervised by the kernel get hard-stop fallback for blocking timed steps. External\nworkers currently rely on cooperative in-process step cancellation.\n\nThe current support posture is documented in [docs/support-matrix.md](./docs/support-matrix.md).\n\n## Start Here\n\n- [First-Run Walkthrough](./docs/first-run.md)\n- [Support Matrix](./docs/support-matrix.md)\n- [Troubleshooting](./docs/troubleshooting.md)\n- [Trust Model](./docs/trust-model.md)\n\n## Quick Start\n\n### Install The Runtime\n\n```bash\ncurl -fsSL https://runtime.vilano.ai/install.sh | bash\nexport PATH=\"$HOME/.vilano/bin:$PATH\"\nvilano version\nvilano doctor\n```\n\nThe installer writes the managed launcher to `~/.vilano/bin/vilano`. Add `~/.vilano/bin` to your\n`PATH` once, then use bare `vilano`. Install Bun `1.3.10+` from [bun.sh](https://bun.sh/) before\nrunning `bun add @vilano/runtime` or authoring Vilano Runtime projects. `install.sh` and\n`vilano update` both default to the stable channel. Alternate release channels can be selected\nwith `VILANO_RELEASE_CHANNEL`.\n\n### Create A Runnable Starter\n\n```bash\nmkdir vilano-starter\ncd vilano-starter\nvilano init . --starter\nbun add @vilano/runtime\nvilano project add . --name vilano-starter\nvilano workflow list --project vilano-starter\nvilano service list --project vilano-starter\nvilano run start vilano-starter/reviewCoordinator --input '{\"repoId\":\"repo_123\",\"note\":\"Ship 0.1\"}'\n```\n\nThe starter writes an explicit `vilano.manifest.json`, a minimal TypeScript workflow/service pair,\nand a local `package.json`. `project add` and `run start` will start the runtime if it is not\nalready running. The starter path is the intended fastest route from install to a running agent\nsystem.\n\nInspect the resulting run and service:\n\n```bash\nvilano run explain \u003crun-id\u003e\nvilano run inspect \u003crun-id\u003e\nvilano run replay \u003crun-id\u003e\nvilano service ask vilano-starter/reviewer status --service-key repo_123 --wait-timeout 30s\nvilano service history vilano-starter/reviewer --service-key repo_123\n```\n\n### Bring An Existing Repo Under Vilano Runtime\n\nAdd the SDK, then generate and review an explicit manifest:\n\n```bash\ncd /path/to/project\nbun add @vilano/runtime\nvilano init .\nvilano project add . --name my-project\nvilano workflow list --project my-project\n```\n\n`vilano init` without `--starter` scans an existing TS/JS project and writes an explicit manifest\nstarting point. Review that manifest before relying on it, especially if your definitions use\nnon-trivial export patterns.\n\nRegistration validates the manifest contract, paths, and declared export names, then imports the\ndeclared definitions from the pinned snapshot to prove definition identity before registration\ncompletes. Activation still re-validates the same identity when the worker imports the module.\n\nBecause of that, treat `vilano project add` and `vilano project sync` as trusted local-code steps.\nIf your project has top-level module side effects, registration can trigger them.\n\nProject-local runtime defaults can live in `vilano.toml` at the repo root:\n\n```toml\n[runtime]\nport = 4141\nexecution_home = \".vilano/execution\"\nmanaged_workers = 2\nrepo_pool_size = 5\n\n[project]\nenv_file = \".env\"\n```\n\nVilano walks up from the current working directory to find the nearest `vilano.toml`. Shell env\nvars still win when both are set.\n\n### Repo Checkout And Examples\n\nFor contributor and repo-checkout workflows, see [docs/development.md](./docs/development.md).\n`bootstrap-demo` is the canonical richer example in the repo. For smaller reference projects, see\n[`examples/multi-agent-demo`](./examples/multi-agent-demo),\n[`examples/approval-loop-demo`](./examples/approval-loop-demo), and\n[`examples/fanout-demo`](./examples/fanout-demo).\n\nRelease-prep and distribution work is documented in [docs/releases.md](./docs/releases.md) and\n[docs/distribution.md](./docs/distribution.md).\n\n## Programming Model\n\n### Workflow\n\n```ts\nimport { workflow } from \"@vilano/runtime\";\n\nexport const planner = workflow({\n  name: \"planner\",\n  run: async (input: { topic: string }, ctx) =\u003e {\n    const research = await ctx.step(\n      \"research\",\n      async () =\u003e ({ topic: input.topic, sources: 3 }),\n      { retry: { retries: 1, backoff: \"50ms\" } }\n    );\n\n    return await ctx.exec({\n      name: \"summarize\",\n      cmd: \"bun\",\n      args: [\"-e\", `console.log(JSON.stringify(${JSON.stringify(research)}))`],\n      capture: { stdout: true },\n      parse: (stdout) =\u003e JSON.parse(stdout.trim()),\n    });\n  },\n});\n```\n\n### Service Agent\n\n```ts\nimport { service } from \"@vilano/runtime\";\n\nexport const reviewer = service({\n  name: \"reviewer\",\n  key: (input: { repoId: string }) =\u003e input.repoId,\n\n  init: async (input) =\u003e ({\n    repoId: input.repoId,\n    notes: [] as string[],\n  }),\n\n  onSend: {\n    hint: async (payload: { note: string }, state) =\u003e ({\n      state: { ...state, notes: [...state.notes, payload.note] },\n    }),\n  },\n\n  onAsk: {\n    status: async (_payload, state) =\u003e ({\n      reply: { ready: true, notes: state.notes.length },\n    }),\n  },\n});\n```\n\nFrom a workflow or service turn:\n\n```ts\nconst reviewerRef = await ctx.connect(reviewer, { repoId: \"repo_123\" });\nawait reviewerRef.send.hint({ note: \"Focus on migrations\" });\nconst status = await reviewerRef.ask.status();\n```\n\n### Agent Runtime Primitives\n\nThese are part of the current TypeScript surface:\n\n- `ctx.monitor(...)`\n- `ctx.link(...)`\n- `ctx.trapExit()`\n- `ctx.nextExit()`\n- `ctx.supervise(...)`\n- `ctx.mailbox()`\n- `ctx.defer(...)`\n- `ctx.reject(...)`\n- `ctx.publish(...)`\n- `ctx.subscribe(...)` / `ctx.unsubscribe(...)`\n- `ctx.lookupSingleton(...)`\n\n## Execution Semantics\n\nVilano recovery reruns workflow or service-turn orchestration code from the top against durable\nkernel state until the next incomplete operation boundary.\n\nThat gives JS/TS BEAM-like operational semantics from the outside while keeping the kernel as the\ndurable source of truth.\n\nDurable boundaries:\n\n- `ctx.step()`\n- `ctx.exec()`\n- `ctx.sleep()`\n- `ctx.waitForSignal()`\n- `ctx.spawn()` / `child.result()`\n- `ctx.connect()` and service `send` / `ask` / `signal`\n- relationship waits such as `ctx.nextExit()`\n\n### `step()` vs `exec()`\n\nUse `step()` for short, replayable in-process logic.\n\nUse `exec()` when the work should be:\n\n- an actual subprocess\n- killable by the runtime\n- observable through stdout/stderr/artifacts\n- isolated from the worker process\n\n### Cancellation and Timeouts\n\n`step()` is cooperative first. Inside a step callback you can use:\n\n- `step.signal`\n- `step.checkCancelled()`\n- `await step.yield()`\n\nFor managed workers, the kernel also has a hard-stop fallback for timed, non-cooperative blocking\nsteps. For unmanaged workers, cancellation and timeout remain durable, but the kernel cannot kill\nthe external worker process.\n\n### Retries\n\nRetries are kernel-scheduled and durable for:\n\n- steps\n- execs\n- service turns\n\nIf a failure should never retry, throw `nonRetryable(...)`.\n\n## Documentation\n\n- [Docs index](./docs/README.md)\n- [Architecture](./docs/architecture.md)\n- [Support matrix](./docs/support-matrix.md)\n- [Development guide](./docs/development.md)\n- [Operations guide](./docs/operations.md)\n- [Manifest guide](./docs/manifests.md)\n- [Protocol guide](./docs/protocol.md)\n- [Release notes guide](./docs/releases.md)\n- [Protocol artifacts](./protocol/README.md)\n- [Test coverage](./tests/README.md)\n- [Contributing](./CONTRIBUTING.md)\n- [Security policy](./SECURITY.md)\n- [Code of conduct](./CODE_OF_CONDUCT.md)\n\n## Repository Layout\n\n- [kernel/](./kernel) — BEAM kernel and durable agent coordination plane\n- [cli/](./cli) — Bun-based operator CLI\n- [sdk/typescript/](./sdk/typescript) — TypeScript SDK\n- [worker/](./worker) — shared JS/TS worker core and runtime-specific entrypoints\n- [examples/](./examples) — reference project definitions and demos\n- [protocol/](./protocol) — versioned transport contract\n- [tests/](./tests) — integration and soak coverage\n\n## Running the Checks\n\n```bash\nbun run typecheck\ndirenv exec . bun run test:kernel\ndirenv exec . bash -lc 'cd kernel \u0026\u0026 mix compile'\ndirenv exec . bun run test\ndirenv exec . bun run smoke:install\n```\n\n## Notes\n\nLong-form design exploration still lives under `spec/` and is intentionally ignored by git. The\ntracked docs in `docs/` describe the codebase and support posture as it exists in the repository.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvilano-ai%2Fruntime","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvilano-ai%2Fruntime","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvilano-ai%2Fruntime/lists"}