Tutorial

Inspect and run a Flint workflow

Use an existing matched Flint project to inspect a two-job JSON workflow, validate Scheme, check operator prerequisites, and inspect real run results on Linux.

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.

Prepare an existing project and an approved host

Use this tutorial to submit the sample's build and test jobs, then read their actual outcomes. It requires an existing authorized Flint project and a matched Rune build. No candidate download is offered here. Set FLINT_PROJECT to the absolute project path.

Read IDENTITY.md, the project README, the generated Rune skill, the modules, and the test environment before running code. Module loading can execute Scheme. Keep a disposable development copy for validation because repo-mode commands can write .rune/ state.

Before executing jobs, have the operator verify supported Linux, cgroup v2, usable namespaces, overlayfs, delegated cgroup permissions, the approved rootfs, and private state storage. Confirm that the rootfs contains the shell and executables needed by each step. Do not use a personal workstation's filesystem as an improvised job root.

The operator supplies RUNE_NATIVE_ROOTFS, RUNE_NATIVE_CGROUP_ROOT, and RUNE_NATIVE_STATE_ROOT for this account. Use a short private state path because Unix socket paths have length limits. Do not invent those paths, grant extra privilege, or reuse a live service's state for a tutorial.

Read the two-job workflow

The existing examples/sample-workflow.json contains this workflow:

{
  "schema_version": 1,
  "name": "sample",
  "jobs": [
    {"id": "build", "needs": [], "steps": [{"run": "true"}]},
    {"id": "test", "needs": ["build"], "steps": [{"run": "true"}]}
  ]
}

Build has no dependencies. Test names build in needs, so it waits for that dependency. Each step runs true inside the prepared sandbox. The workflow does not install a toolchain or verify your real project. A sample success would establish only that these sample jobs executed in this environment.

Keep the file unchanged for the first attempt. Use workflow reference before adding resource requirements, actions, services, or matrix expansion.

Check the Scheme before submitting jobs

Use the matched Rune already installed on the host:

rune --version
rune --help
rune steel fmt --check --repo "$FLINT_PROJECT"
rune steel check --repo "$FLINT_PROJECT"

Expect formatting diagnostics or a clean check, then the module-load result. For the capsule tests, inspect the supplied tests/operator-test-env.sh first. It configures test fixtures and capability policy. Use the project's isolated test setup, then run rune steel test --repo "$FLINT_PROJECT". Do not source a fixture environment into a production service.

Read every failing file and assertion. A Scheme pass on macOS proves only the exercised Scheme or control-plane behavior. It does not execute supported Linux jobs or establish release acceptance. This tutorial supplies no fabricated successful test output.

Run the sample on prepared Linux

Continue only when the operator has provided the approved native settings for this isolated project. The following command executes work. It is not a dry run:

rune --json exe --repo "$FLINT_PROJECT" run \
	--workflow examples/sample-workflow.json --format json

Read the actual CLI envelope and the reported artifact path. The handler writes a result.json artifact containing the domain response. Record the returned run_id from the stored run. The global command can report successful invocation even when a job outcome needs attention. Inspect run status instead of relying on the human summary.

If native sandbox setup fails, stop here and read the error. Do not label a control-plane submission as a successful Linux execution. The diagnostic guide distinguishes setup failure, job failure, and publication failure.

Read the run and job logs

Set RUN_ID to the identifier actually returned by your invocation. Use the same project and state directory:

rune --json exe --repo "$FLINT_PROJECT" status --run-id "$RUN_ID"
rune --json exe --repo "$FLINT_PROJECT" logs --run-id "$RUN_ID" --job build
rune --json exe --repo "$FLINT_PROJECT" logs --run-id "$RUN_ID" --job test
rune --json exe --repo "$FLINT_PROJECT" explain --run-id "$RUN_ID"
rune --json exe --repo "$FLINT_PROJECT" resources
rune --json exe --repo "$FLINT_PROJECT" health

Read each result.json artifact. Compare the expected two jobs with the stored jobs and their terminal states. true need not print output, so an empty log is not evidence of a skipped or successful job. Use status and explain to establish what happened.

Health reports service, queue, publication, resource, and full-run fields. A repo-mode command does not imply a ready long-lived service or background workers. Before repeating side-effecting work, read replay and cancellation. Before hosting a named Flint, follow Rune's explicit deployment boundary and arrange operator supervision separately.

Back to top