urirun://project/home

One URI registry for commands across code, shell, containers, and services.

Declare a route once, compile it into a registry, and call the same URI in-process or over HTTP, gRPC, a queue, serverless, Docker, MCP, or an A2A agent card.

Start with v2 CLI commands

quickstart GitHub install

curl -fsSL https://ifuri.com/urirun/install.sh | sh
urirun --help
urirun scan ./project \
  --out generated/bindings.v2.json \
  --registry-out generated/registry.json
urirun list generated/registry.json
urirun run 'tool://local/report/render' --registry generated/registry.json

Runtimeurirun

Repositorytellmesh/urirun

Default contractv2 JSON Schema

Executiondry-run first

urirun://schema

One contract, many runtimes.

Packaging commands starts with a schema. A decorator, helper, or artifact scan generates a binding, then urirun compiles it into a registry and runs the same URI everywhere.

fn Write a function Types and defaults are the source of truth.

{ } Generate a binding inputSchema plus argv or shell template is emitted.

✓ Compile registry Routes are validated and discoverable.

▶ Run the URI Dry-run first; execute only after policy allows it.

decorator + Pydantic

The decorator turns a function signature into a binding.

Types and defaults become JSON Schema, while the returned argv list becomes a deterministic command template.

declaration

import urirun
from urirun.v2 import decorated_bindings

@urirun.command("media://local/video/transcode")
def transcode(input: str, output: str, width: int = 1280, height: int = 720):
    return ["ffmpeg", "-i", "{input}", "-vf", "scale={width}:{height}", "{output}"]

binding + registry

from urirun.v2 import compile_registry, decorated_bindings

bindings = decorated_bindings()
registry = compile_registry(bindings)

plain JS helper

A small JS helper emits bindings without a transpiler.

Field declarations produce inputSchema, and the command factory returns argv placeholders.

declaration

import { bindingDocument, string, uriCommand } from "./uri-command.mjs";

const greet = uriCommand(
  "js://local/greet/message",
  { name: string({ required: true }) },
  ({ name }) => ["node", "-e", "console.log(process.argv[1])", name],
);

binding + registry

node generate-bindings.mjs > generated/bindings.v2.json
python -m urirun.v2 compile generated/bindings.v2.json \
  --out generated/registry.json

firmware route table

Firmware can expose a small URI route table.

C handles local dispatch, while a generated registry gives the rest of the system the same contract.

declaration

static const UriRoute routes[] = {
  {"firmware://device-01/led/command/set", led_set},
  {"firmware://device-01/telemetry/query/latest", telemetry_latest},
};

binding + registry

python -m urirun.v2 add-command "firmware://device-01/led/command/set" \
  --argv "./firmware-cli led set {state}" \
  --param state:boolean:required \
  --out generated/bindings.v2.json
python -m urirun.v2 compile generated/bindings.v2.json --out generated/registry.json

scan scripts

A shell script becomes a URI by scanning the project.

Existing scripts stay in place. urirun scans them and creates bindings for controlled execution.

declaration

#!/usr/bin/env bash
# scripts/render-report.sh
set -euo pipefail
echo "report for ${1:-today}"

binding + registry

python -m urirun.v2 scan ./scripts \
  --out generated/bindings.v2.json \
  --registry-out generated/registry.json

image label + manifest

A Docker image points to its URI manifest.

The container carries bindings.json, and Dockerfile scanning collects manifests into the shared registry.

declaration

FROM python:3.12-slim
LABEL io.tellmesh.urirun.manifest="/app/bindings.json"
COPY bindings.json /app/bindings.json
COPY worker.py /app/worker.py

binding + registry

python -m urirun.v2 scan ./docker-stack \
  --out generated/bindings.v2.json \
  --registry-out generated/registry.json

decorator-style declaration

A TS decorator gives a typed command declaration.

The method returns argv, while decorator fields become the runtime input schema.

declaration

class MathCommands {
  @uriCommand("ts://local/math/add", {
    a: { type: "integer", required: true },
    b: { type: "integer", default: 0 },
  })
  add({ a, b }) {
    return ["node", "-e", "console.log(Number(process.argv[1]) + Number(process.argv[2]))", a, b];
  }
}

binding + registry

npx tsx decorators.ts > generated/bindings.v2.json
python -m urirun.v2 compile generated/bindings.v2.json \
  --out generated/registry.json

PHP 8 attribute + reflection

A PHP attribute generates a binding through reflection.

Function parameters become inputSchema, and the attribute carries URI plus argv.

declaration

#[UriCommand(
  uri: "php://local/slug/create",
  argv: ["php", "-r", "echo strtolower($argv[1]);", "{text}"],
)]
function slug(string $text, int $limit = 64): void {}

binding + registry

php examples/php/generate-bindings.php > generated/bindings.v2.json
python -m urirun.v2 compile generated/bindings.v2.json \
  --out generated/registry.json

flow://registry/build

Use existing artifacts as URI packages.

The useful path is not writing a new SDK. Point urirun at what your project already ships, generate bindings, validate the registry, and run by URI.

repo://project/artifacts/query/scan

Scan artifacts

Read Dockerfile labels, package metadata, Make targets, shell scripts, and explicit bindings.

registry://local/routes/command/compile

Compile a registry

Turn portable binding files into one lookup tree for every runtime.

policy://local/execution/query/check

Gate execution

Dry-run first, then require allow rules for real argv, shell, Docker, or network calls.

flow://local/task/command/run

Run the same URI

Call it from shell, backend, browser, Docker service, MCP tool, or A2A agent card.

transport://any/adapter/query

Same URI, different runtime.

A URI names what should run. The transport decides how it runs: in-process, argv, shell, Docker, HTTP, gRPC, a message queue, serverless, MCP, or A2A. The contract and the policy gate stay in one place.

in-process v2.run / local-function dispatch

argv Safe argument templates, no shell

shell Policy-gated shell templates

Docker docker-run / docker-exec, image labels

HTTP v2_service: POST /run, GET /routes

gRPC v2_grpc: Run, RunStream, ListRoutes

queue topic -> v2.run consumer (MQTT/NATS/Kafka shape)

serverless pure handler(event) function

MCP / A2A tools/list, tools/call, agent card

docs://local/index/query

Documentation.

Install One-line curl installer, PATH setup, and first urirun command. Getting started Install from GitHub, scan artifacts, validate, and run the first URI. Naming Where to use urirun and how to keep older project names out of new code. Commands CLI commands, versioned entry points, and one-line binding generation. Registry How portable binding documents become dispatchable runtime routes. Transports Local functions, shell, Docker, HTTP, gRPC, browser, MCP, and A2A. Logo Generated SVG assets for icon, wordmark, favicon, and lockups. Roadmap Practical next work for making urirun easier to use.

examples://repo/current/query

Examples that show the layers working together.

The examples are intentionally small: they show how one registry can be used by browser UI, backend services, Docker workers, generators, and firmware-style adapters.

Four noVNC desktops (pc1 controller, pc2 service-node, pc3 client-node, pc4 monitor-node) in one dashboard, each terminal streaming URI-flow JSON events — novnc_lan_flow: four Docker computers communicating over one URI contract (pc://…, log://…), shown together in a dashboard.

v2/examples/transports

One registry driven over five transports (in-process, queue, serverless, HTTP, gRPC) plus a simple scan & run.

v2/examples/multi_transport

Docker stack mixing HTTP and gRPC workers: auto-generated registry, conflict detection, and a cross-environment flow.

v2/examples/docker_uri_flow

Docker Compose services communicating through generated URI bindings, with a library-native service dispatcher.

v2/examples/novnc_lan_flow

Four noVNC computers in one Docker LAN, shown together in a dashboard and coordinated by a URI flow.

v2/examples/html_uri_app

Browser UI that calls a Python backend through URI actions and exposes logs, MCP tools, and an A2A card.

v2/examples/generators

JS, Node.js, TypeScript, and PHP declarations that generate the same v2 binding contract.

examples/reference_adapters

Minimal adapters for JavaScript, Python, C/firmware, and browser use.

todo://urirun/usability/query

Next usability work.

urirun init for a starter registry, policy, and example route
urirun doctor for environment, dependency, port, and route conflict checks
urirun serve for a local route browser, log viewer, dry-run console, and policy-gated execution
standard log:// routes across frontend, backend, shell, firmware, and Docker examples
urirun diff for comparing registries before deployment