Skip to content
runy

Getting started

  1. Mark the workspace root. A workspace is the folder that holds a .runy.json (or .runy.yaml, .runy.yml, .runy.toml). An empty object is enough:

    .runy.json
    {}

    runy finds the root by walking up from the current directory, so every command below works from any folder inside it.

  2. Write a namespace. A namespace is a .runy/ folder; each *.yaml in it holds resources, separated by ---. The namespace is named after the folder that holds .runy/, here web:

    • .runy.json
    • Directoryproducts
      • Directoryweb
        • Directory.runy
          • dev.yaml
        • package.json
        • Directorysrc/
          • …
    products/web/.runy/dev.yaml
    kind: port
    name: web
    spec:
      preferred: 3010
      domains: [web.localhost]
    ---
    kind: process
    name: web
    spec:
      cmd: pnpm
      args: [dev, --port, "${ port.web.status.value }"]
      cwd: products/web
      restart: { kind: fixed, delay: 1000, max_restarts: 5, on: failure }
      health:
        http:
          http: { port: "${ port.web.status.value }" }
          initial_delay: 2
          period: 1
          failures: 60

    The port asks for 3010 and falls back to a free port between 3000 and 3999. The process reads the port’s published value through an expression, so it is held back until the port has one. The health check probes http://localhost:<port>/ every second and restarts the dev server after a minute of failures.

  3. Activate it.

    Terminal window
    cd products/web
    runy ns up

    With no names, runy ns up activates the namespace enclosing the current directory. The first CLI call starts the daemon in the background; it stays up after the shell closes. The active set is remembered, so the dev server is back after a reboot as soon as any runy command runs.

  4. Look at it.

    Terminal window
    runy ps
    ┌───────────┬───────────┬─────────────────┬───────────┬─────────────────────────────┐
    │ Workspace │ Namespace │ Resource        │ Condition │ Status                      │
    ├───────────┼───────────┼─────────────────┼───────────┼─────────────────────────────┤
    │ umka      │ web       │ web/port/web    │ Resolved  │ 3010 → http://web.localhost │
    │ umka      │ web       │ web/process/web │ Resolved  │ running healthy             │
    └───────────┴───────────┴─────────────────┴───────────┴─────────────────────────────┘

    http://web.localhost reaches the dev server through the daemon’s proxy. The console at http://localhost:4122 shows the tree, each resource’s spec, status and condition, and streams the process’s output.

  5. Change something. Edit dev.yaml and save. The daemon re-reads the file, re-renders every resource and applies only what differs: a new args restarts the process, a new max_lines for its journal does not, a typo in a field name shows up as a diagnostic in runy ns and the console before anything runs.

Day to day

Section titled “Day to day”
Terminal window
runy ns                                  # every namespace, active or not, with diagnostics
runy ns down                             # stop this namespace's resources
runy signal web/process/web restart      # restart one process
runy signal workspace restart            # re-read the resource files (without watchman)
runy daemon stop                         # stop the daemon and everything it runs