# simrun

> Runner of simulation workflows on a k3s cluster with Argo Workflows and Kueue, for people and agents

The links below point to the markdown source of the documentation. [llms-full.txt](https://matthiaskoenig.github.io/simrun/llms-full.txt) contains all of it in a single file.

## Documentation

- [Home](https://matthiaskoenig.github.io/simrun/index.md): `simrun` runs simulation workflows on a small cluster of servers with k3s, Argo Workflows and Kueue.
- [Installation](https://matthiaskoenig.github.io/simrun/installation.md): `simrun` needs python 3.14 or newer and runs on Linux.
- [Concepts](https://matthiaskoenig.github.io/simrun/concepts.md): This page explains how `simrun` turns a submitted workflow into pods on the cluster and what it records.
- [Release notes](https://matthiaskoenig.github.io/simrun/release-notes.md): The notes of every release, newest first.
- [Development](https://matthiaskoenig.github.io/simrun/development.md): Contributions are welcome.

## Usage

- [Workflows](https://matthiaskoenig.github.io/simrun/workflows.md): A workflow is a YAML file of tasks, usually kept in the repository of a project, such as `pkdb_models/caffeine_pbpk/workflows/fit.yaml`.
- [Command line](https://matthiaskoenig.github.io/simrun/command-line.md): `simrun` is the command line of people and scripts: it submits, follows, compares, cancels and cleans up runs, and `simrun edit` opens a workflow file in the Editor of the web app.
- [Local mode](https://matthiaskoenig.github.io/simrun/local.md): The local mode runs a workflow on this machine, without a cluster, a registry or a mounted store.
- [Agents and MCP](https://matthiaskoenig.github.io/simrun/mcp.md): `simrun-mcp` is an MCP server on stdio, a local process of an agent: it runs on the machine of the working trees, takes the snapshots of the sources the agent names and calls the service with the token of the agent.
- [Web app](https://matthiaskoenig.github.io/simrun/web-app.md): The service serves a web app at `/ui/`, e.g.
- [Plugins](https://matthiaskoenig.github.io/simrun/plugins.md): A task type comes from a plugin: a python package with entry points of the group `simrun.task_types`, each a `simrun.plugins.TaskType`.

## Operation

- [Service](https://matthiaskoenig.github.io/simrun/service.md): The service is the API (FastAPI) which the command line, the MCP server and scripts call, and the controller behind it, which runs the submissions in the background and follows the workflows of the runs.
- [Cluster deployment](https://matthiaskoenig.github.io/simrun/deployment.md): `simrun` runs on a k3s cluster of dedicated Linux servers.
- [Testing](https://matthiaskoenig.github.io/simrun/testing.md): The tests are written with pytest and live in `tests/`.

## API reference

- [Overview](https://matthiaskoenig.github.io/simrun/api/index.md): The API reference is generated from the docstrings of the package.
- [workflow](https://matthiaskoenig.github.io/simrun/api/workflow.md): The workflow model: tasks, the references between them and their order.
- [plugins](https://matthiaskoenig.github.io/simrun/api/plugins.md): The plugin interface: task types, their resource hints and their discovery.
- [plugins_builtin](https://matthiaskoenig.github.io/simrun/api/plugins_builtin.md): The built-in task types.
- [demo](https://matthiaskoenig.github.io/simrun/api/demo.md): The demo plugin: sums of squares, split into one unit per number.
- [client](https://matthiaskoenig.github.io/simrun/api/client.md): The client of the service: snapshots working trees, then calls the API.
- [cli](https://matthiaskoenig.github.io/simrun/api/cli.md): The command line of simrun: submit, follow and compare runs.
- [local](https://matthiaskoenig.github.io/simrun/api/local.md): The local service of a project: the service with the local backend in `.simrun/`.
- [mcp](https://matthiaskoenig.github.io/simrun/api/mcp.md): The MCP server of simrun, a local stdio process of an agent.
- [planner](https://matthiaskoenig.github.io/simrun/api/planner.md): The planner: the shape of a worker pod and the number of pieces of a task.
- [resources](https://matthiaskoenig.github.io/simrun/api/resources.md): Resources learned from the reports of workers.
- [ledger](https://matthiaskoenig.github.io/simrun/api/ledger.md): The unit ledger: workers of a split task claim units through atomic renames.
- [worker](https://matthiaskoenig.github.io/simrun/api/worker.md): The worker harness: a pod of a split task computes units of the ledger in a pool.
- [cgroup](https://matthiaskoenig.github.io/simrun/api/cgroup.md): The limits and the usage of the cgroup (v2) a worker runs in.
- [snapshot](https://matthiaskoenig.github.io/simrun/api/snapshot.md): Snapshots of working trees with provenance.
- [environment](https://matthiaskoenig.github.io/simrun/api/environment.md): The environment of a run: a lock from the model and its snapshotted libraries.
- [store](https://matthiaskoenig.github.io/simrun/api/store.md): The run store: run records and the layout of a run on the shared drive.
- [config](https://matthiaskoenig.github.io/simrun/api/config.md): The configuration of the cluster the runs are submitted to.
- [podspec](https://matthiaskoenig.github.io/simrun/api/podspec.md): The parts of a pod which every backend shares: image, shapes, command, environment.
- [argo](https://matthiaskoenig.github.io/simrun/api/argo.md): Argo workflows from runs: one DAG, a scatter of workers per split task.
- [cwl](https://matthiaskoenig.github.io/simrun/api/cwl.md): CWL v1.2 workflows from runs, executed with cwltool (or Toil on Slurm).
- [testing](https://matthiaskoenig.github.io/simrun/api/testing.md): A backend in memory for tests of the service, advanced by the test.
- [app](https://matthiaskoenig.github.io/simrun/api/service.app.md): The API of the service: people and agents submit, follow and compare runs.
- [auth](https://matthiaskoenig.github.io/simrun/api/service.auth.md): Identities of the callers of the service and the priorities of their runs.
- [backend](https://matthiaskoenig.github.io/simrun/api/service.backend.md): The backend the service runs workflows on: Argo Workflows, or a fake in tests.
- [argo_backend](https://matthiaskoenig.github.io/simrun/api/service.argo_backend.md): The backend of the service on a cluster: Argo Workflows, Kueue and BuildKit.
- [local_backend](https://matthiaskoenig.github.io/simrun/api/service.local_backend.md): The local backend: the pods of a run as processes on this machine.
- [local_env](https://matthiaskoenig.github.io/simrun/api/service.local_env.md): The environment of a local run with snapshots: a venv of the run.
- [controller](https://matthiaskoenig.github.io/simrun/api/service.controller.md): The controller: follows the workflows of the runs and records their end.
- [submission](https://matthiaskoenig.github.io/simrun/api/service.submission.md): The submission of a run in the background: its environment, image and workflow.
- [index](https://matthiaskoenig.github.io/simrun/api/service.index.md): The index of the runs in SQLite (spec section 4), beside the run store.
- [logs](https://matthiaskoenig.github.io/simrun/api/service.logs.md): The logs of the pods of a task, kept in the run store.
- [compare](https://matthiaskoenig.github.io/simrun/api/service.compare.md): The comparison of runs: provenance and the summaries of their tasks side by side.

## Optional

- [Repository](https://github.com/matthiaskoenig/simrun): source code, issues and releases.
- [Sitemap](https://matthiaskoenig.github.io/simrun/sitemap.xml): all pages of the rendered site.
- [objects.inv](https://matthiaskoenig.github.io/simrun/objects.inv): the API objects of the reference as a sphinx inventory.