Using the Scheduler

Introduction

The scheduler is the Fastpath service that manages access to SUT classes and dispatches queued work onto concrete SUTs as they become available. It supports two main workflows:

  • Plan execution: submit a plan that targets a SUT class and let the scheduler split and run it across all available SUTs.

  • Manual leasing: acquire a SUT from a SUT class for interactive use, then release it when finished.

This guide walks through setting up a small demo scheduler instance, saving the scheduler URL and user token in Fastpath preferences, and then using the scheduler CLI verbs to submit and manage plans and leases.

Note

For low-level integration details and the REST interface itself, see Scheduler REST API.

Start a Demo Scheduler

For a simple demo, use the built-in static SUT provider. Create a file called sutclasses.yaml:

- sutclass: demo
  type: static
  params:
    suts:
      - name: demo-01
        connection:
          method: SSH
          params:
            host: demo-01
            user: fpuser
            keyfile: /path/to/id_ed25519
      - name: demo-02
        connection:
          method: SSH
          params:
            host: demo-02
            user: fpuser
            keyfile: /path/to/id_ed25519

This defines a SUT class called demo containing two static SUTs.

Start the scheduler:

fastpath sched run \
  --host 127.0.0.1 \
  --port 5000 \
  --database sqlite:///scheduler.db \
  --storage ./sched_storage \
  --sutclasses ./sutclasses.yaml

If you want scheduled plans to automatically publish into a resultstore, also provide --resultstore:

fastpath sched run \
  --host 127.0.0.1 \
  --port 5000 \
  --database sqlite:///scheduler.db \
  --storage ./sched_storage \
  --sutclasses ./sutclasses.yaml \
  --resultstore sqlite:///scheduler-results.db

On first start the scheduler creates a default admin user and prints its token. The admin user has all capabilities, including admin:

****
Created default admin user 'admin' with token: <token>
****

Keep that token. It is needed to create additional scheduler users.

Save the Scheduler URL and Token

The scheduler CLI verbs take --url and --token options, but it is much more convenient to store them as Fastpath preferences:

fastpath preference set --category sched --name url http://127.0.0.1:5000
fastpath preference set --category sched --name token <admin-token>

Now scheduler commands can be run without repeating either argument; if –url or –token is omitted, they default to the values saved as preferences. For example:

fastpath sched sutclass-list

You can inspect the saved values with:

fastpath preference get --category sched --name url
fastpath preference get --category sched --name token

Create Scheduler Users

Create users with the sched user-create verb. Capabilities are passed as a comma-separated list of lower-case names.

For example, create a user that can execute plans and query scheduler state:

fastpath sched user-create alice --capabilities exec,query

Or create a user that can manually lease SUTs and query scheduler state:

fastpath sched user-create bob --capabilities lease,query

Each command prints the created user’s token. If you want to work as that user, update the saved sched.token preference to the new token (or pass it with –token).

Inspect the Scheduler State

List known SUT classes:

fastpath sched sutclass-list

This shows the SUT class id, name, whether it is enabled, current usage, and creation time.

To report usage over a specific time window, provide --from and/or --to:

fastpath sched sutclass-list --from 2026-03-01
fastpath sched sutclass-list --from 2026-03-01 --to 2026-04-01

Submit a Plan

Plans submitted to the scheduler must target a SUT class rather than a specific SUT. For example:

sut:
  sutclass: demo
swprofiles:
  - name: baseline
    kernel: /path/to/Image
    modules: /path/to/modules.tar.xz
benchmarks:
  - include: speedometer/v2.1.yaml
  - include: mmtests/kernbench.yaml
defaults:
  benchmark:
    warmups: 1
    repeats: 3
    sessions: 3
    timeout: 1h

Submit it to the scheduler:

fastpath sched plan-exec demo-plan.yaml

Optionally set a priority:

fastpath sched plan-exec --priority 8 demo-plan.yaml

If the scheduler was started with --resultstore, scheduled plan results are published there by default. To queue a plan without publishing its results:

fastpath sched plan-exec --no-publish demo-plan.yaml

If the plan references local files (e.g. kernel or modules), the scheduler client automatically uploads them along with the plan payload.

Track and Manage Plans

List all plans:

fastpath sched plan-list --all-users

Inspect specific plan by id:

fastpath sched plan-list 12

The plan listing shows:

  • the owning user

  • the target SUT class

  • plan priority

  • progress as completed_jobs/total_jobs

  • plan status

  • queued, started, and completed timestamps

Filter plan listings:

fastpath sched plan-list --states running
fastpath sched plan-list --users alice
fastpath sched plan-list --all-users --all-states

By default, plan-list filters to the authenticated user and to plans in the queued or running states. Use --all-users and --all-states to remove those default filters.

Update the priority of a queued or active plan:

fastpath sched plan-update 12 --priority 3

Cancel a plan:

fastpath sched plan-cancel 12

Cancellation is best-effort. Queued child jobs are cancelled immediately. Already-running child jobs are allowed to finish naturally.

Acquire a Lease

To request a manual lease on a SUT from a SUT class:

fastpath sched lease-acquire demo

To wait until the lease becomes active and a concrete SUT has been assigned:

fastpath sched lease-acquire demo --wait

The command prints the lease details, including the assigned SUT once it is available.

Manage Leases

List all leases:

fastpath sched lease-list --all-users

Inspect a specific lease by id:

fastpath sched lease-list 7

Filter lease listings:

fastpath sched lease-list --states acquired
fastpath sched lease-list --users bob
fastpath sched lease-list --all-users --all-states

By default, lease-list filters to the authenticated user and to leases in the queued or acquired states. Use --all-users and --all-states to remove those default filters.

Release a lease when finished:

fastpath sched lease-release 7