Tutorial

Prepare and run your first Rune

A Rune tutorial from download inspection and license review through named-home provisioning, Scheme validation, optional Git main deployment, and graceful shutdown.

Preview contract. These operational guides describe unreleased source, not a shipped-release or deployment claim. Match your build's help and bundled skill before using commands. Check compatibility.

Inspect the release before you install

Build a small personal Rune whose describe function says what it does. Stop after provisioning if you only want a checkout. Starting a process and pushing a deployment are later, explicit steps.

  1. Read the v0.1.5 personal-use agreement. Continue only within that grant or your separate written license.
  2. Check your operating system and CPU against the platform matrix. A supported archive does not establish that every application or native job works on that host.
  3. Open the existing installer inspection page and release notes and checksums. Read the script before executing it. Inspect its release destination, version selection, download redirects, checksum verification, extraction, and binary replacement.
  4. If using an archive, download the exact target and its checksum file together. Compare the SHA-256 digest before extracting or executing. On Linux, use sha256sum --check FILE.sha256. On macOS, use shasum -a 256 --check FILE.sha256 in the archive directory. Replace FILE with the actual downloaded filename. A mismatch means stop.
  5. Use the inspected release's installation instructions. The homepage's agent prompt keeps inspection before execution. No candidate archive or installer is offered here.

The source installer defaults to $HOME/.local/bin and accepts --version X.Y.Z and --bin-dir DIR. Confirm those options in the script you actually downloaded. Check your shell's selected executable with command -v rune, then inspect it:

rune --version
rune --help
rune skills

Expect a version string, command help, and a bundled Scheme skill. These are compatibility checks, not evidence that the candidate behavior is in the release. If an existing public release location is missing or redirects unexpectedly, stop and confirm the intended release with Pearl Computing. This guide does not resolve release-repository naming or availability.

Provision a home without starting it

Use the candidate commands below only after matching your build. Choose an unused lowercase name such as hello. Names contain a leading letter or digit followed by lowercase letters, digits, or hyphens, up to 63 characters.

rune --home "$HOME/.rune" init hello
rune --home "$HOME/.rune" skills hello
rune --home "$HOME/.rune" status hello

init provisions $HOME/.rune/hello, including the source checkout, config, managed Git repository, keys, and guidance. It does not start a process. Expect status to report a stopped process, not a serving endpoint. Do not infer a running process from files on disk.

Read the entire generated rune-scheme-stdlib skill at the path reported by skills hello. Save the clone guidance for later. Work in the provisioned source checkout now. Do not copy private keys into your project.

Give the program a purpose and test it

  1. Open $HOME/.rune/hello/source/IDENTITY.md. Describe the personal project's mission, boundaries, and visible success criteria.
  2. In modules/main.scm, keep the generated module, export, documentation comments, and software loop. Replace only the string returned by describe with Hello from my personal Rune..
  3. In tests/main_test.scm, replace the old expected message with the same string. Keep both named assertions. Align the checkout README with the new purpose.

The resulting function and test follow the generated scaffold:

;;! @export describe
;;! Describe this Rune's purpose.
;;! @signature (describe)
(define (describe)
	"Hello from my personal Rune.")
(require "../modules/main.scm")
(and
	(rune-test/assert-true (string? (describe)) "describe returns a string")
	(rune-test/assert-true
		(equal? (describe) "Hello from my personal Rune.")
		"describe message is stable"))
cd "$HOME/.rune/hello/source"
rune steel fmt --repo "$PWD"
rune steel fmt --check --repo "$PWD"
rune steel check --repo "$PWD"
rune steel test --repo "$PWD"
rune steel docs generate --repo "$PWD"

Expect the formatter to report changes or a clean check, the loader to report the entry module, and the test command to report its actual pass and failure counts. Documentation generation writes four reference and index files. No success transcript is implied here. If a command fails, fix the named file or assertion before proceeding.

These commands work without a running Rune. Loading a Scheme module can execute its top-level code, so inspect untrusted code before check, tests, or REPL. Keep the checkout's .rune/ ignored.

Start and deploy only when you are ready

The tutorial's describe function does not declare a CLI command or HTTP route. Its deployment tests the authoring flow. To add an interface, use the Scheme contracts and the HTTP guide.

  1. In a separate terminal, start the named Rune in the foreground:
rune --home "$HOME/.rune" start hello

Keep that terminal open. start owns the runtime lock and serves managed Git SSH. In your authoring terminal, inspect status and stage only your intended files:

rune --home "$HOME/.rune" status hello
cd "$HOME/.rune/hello/source"
git diff
git add IDENTITY.md README.md modules/main.scm tests/main_test.scm docs
git commit -m "describe my personal Rune"
git push origin main
rune --home "$HOME/.rune" --json status hello

Git main is the deployment boundary. Expect the push to validate the candidate and activate an immutable bundle before main advances. Read push diagnostics and the returned status. A successful local check is not proof of activation. A rejected push preserves the previous active deployment and visible main.

For a separate working copy after start, use rune --home "$HOME/.rune" git clone hello ./hello-copy. The helper uses the managed writer key and pinned host entry. Never invent a remote URL or disable host-key verification to make a clone work.

Stop the foreground process

In the terminal that runs start hello, press Ctrl+C. SIGINT and SIGTERM use the graceful shutdown path. There is no Rune stop or restart command, and Rune does not daemonize.

rune --home "$HOME/.rune" status hello

Expect a stopped process and no live endpoints after shutdown. The home and durable data remain. If you need supervision, generate a service definition and review it separately. Generated definitions do not install or enable themselves.

Back to top