From a DAG to your first AkôFlow run

With AkôFlow Desktop already installed, your first experiment can start on your own workstation. Describe one activity in YAML, select your local machine, and watch a real execution produce a file. Then turn that first activity into a small analysis pipeline.

This walkthrough uses AkôFlow Desktop throughout. Desktop starts its matching local services and manages the connection to the engine. You do not need to clone the source repository, start a development Compose stack, or copy an API token.

What you will build

Begin with write-report: one activity that writes result.txt and prints its contents in the activity log. This checks the complete path from a definition to a local execution and its recorded output.

After that succeeds, import a second YAML with three activities: prepare three measurements, compute their mean, and write a report. The expected answer is 4.00.

Both examples use a small BusyBox container on your local Docker engine. They perform real execution. They do not simulate work or allocate cloud machines.

1. Begin after Desktop is installed

This walkthrough starts after installing AkôFlow Desktop. If you still need the application, follow Install AkôFlow Desktop, then return here.

1. Start Docker and open the installed AkôFlow Desktop application.
2. Let the engine checkup finish and wait for Overview.
3. Confirm Connected at the bottom-left corner.
4. Start with Infrastructure → Environments in the sidebar.

The screenshots below were captured from the actual interface. They show the controls using an existing reference instance: its workflow is named hello, its activity is a, and its local environment is Local environment. For your experiment, enter the tutorial names first-local-check, write-report, Local check, and First local scope. Your fresh catalogs may be empty. The reference run's counts and files are identified in each caption rather than presented as your experiment's results.

Each red number has a matching instruction below the image. Click a screenshot to enlarge it with its arrows; on a phone, scroll the enlarged view sideways to read the controls.

Begin on Overview after installation

The capture shows an existing instance. Your fresh installation can have empty catalogs.

1. Confirm that the bottom-left indicator says Connected.
2. Open Infrastructure → Environments to create your local target.

Begin on Overview after installation

On a small screen, scroll sideways to inspect each control.

1. Confirm that the bottom-left indicator says Connected.
2. Open Infrastructure → Environments to create your local target.

Checkpoint: Desktop is connected. If startup fails, open its failure details before retrying.

2. Connect your local machine

Open Infrastructure → Environments. To create the environment from scratch, follow the two screens below. If you already created Local check, open it and continue with its connection check instead.

Open the local environment setup

Use the execution-infrastructure catalog for this real local workflow.

1. Select Connect environment. Some releases call this New environment.
2. Keep Execution infrastructure selected.

Open the local environment setup

On a small screen, scroll sideways to inspect each control.

1. Select Connect environment. Some releases call this New environment.
2. Keep Execution infrastructure selected.

1. Select Connect environment (called New environment in some releases), then Local machine.
2. Name it Local check.
3. Select Test connection.
4. When the test succeeds, select Save environment.

Create Local check

This form has only been filled for the capture: Save environment becomes available after a successful connection test.

1. Choose Local machine.
2. Enter Local check as the environment name.
3. Select Test connection and wait for success.
4. After the test succeeds, select Save environment.

Create Local check

On a small screen, scroll sideways to inspect each control.

1. Choose Local machine.
2. Enter Local check as the environment name.
3. Select Test connection and wait for success.
4. After the test succeeds, select Save environment.

On the environment page, select Check now. Wait until Local machine shows online. This makes the local resource available for planning.

An environment describes where the work can run. Here, the target is the machine reached through your local AkôFlow engine. Desktop requests connection checks from the daemon.

Check that the local machine is online

Open the environment you created. This reference environment is already online; your tutorial environment is named Local check.

1. Select Check now to request a fresh connection check.
2. Continue when the local connection reads online.

Check that the local machine is online

On a small screen, scroll sideways to inspect each control.

1. Select Check now to request a fresh connection check.
2. Continue when the local connection reads online.

Checkpoint: the local resource is online. Remember its environment name for step 5.

3. Save your first workflow YAML

Create a plain-text file named first-local-check.yaml, or download the complete YAML. Copy the whole document, preserving indentation, and save it with the .yaml extension.

name: first-local-check
spec:
  namespace: learning
  activities:
    - name: write-report
      cpuLimit: "0.1"
      memoryLimit: 32Mi
      command:
        executable:
          source:
            type: oci
            reference: docker.io/library/busybox:1.36
          delivery:
            strategy: auto
            targetFormat: oci
        entrypoint: sh
        arguments:
          - -c
          - |
            printf 'Akoflow local check\n' > result.txt
            cat result.txt
      expectedOutputs: [result.txt]

Read the document from the outside in:

• name identifies the workflow. namespace groups it under learning.
• activities contains one unit of work: write-report.
• command.executable names the BusyBox image. targetFormat: oci selects the container format used by local Docker.
• entrypoint: sh and the -c argument run the following shell script.
• printf creates the file in the activity workspace. cat prints it into the activity log.
• expectedOutputs asserts that result.txt exists after execution.
• CPU and memory limits describe the activity's small resource demand.

The image comes from Docker Hub, so its first use may take longer while it downloads. For a research reproducibility bundle, also retain the resolved image digest alongside the version tag.

4. Import the YAML in Desktop

Import the workflow you saved

The catalog can already contain other workflows. Import your first-local-check.yaml file.

1. Select Import YAML, then choose first-local-check.yaml.
2. Find this catalog under Workflows → Definitions.

Import the workflow you saved

On a small screen, scroll sideways to inspect each control.

1. Select Import YAML, then choose first-local-check.yaml.
2. Find this catalog under Workflows → Definitions.

1. Open Workflows → Definitions.
2. Select Import YAML and choose first-local-check.yaml.
3. Open the new first-local-check definition.
4. Confirm that the DAG contains one activity named write-report.

A DAG is a directed acyclic graph: nodes are activities and arrows are dependencies. This first graph has one node and no arrows, enough to learn the execution lifecycle before adding data handoffs.

If the name already exists, open the existing definition or change name before importing another copy. The importer normalizes names into identifiers, so each new definition needs a distinct name.

Checkpoint: the definition exists and its graph matches the YAML. Importing saves a definition; it does not start a run.

5. Create a local execution scope

Create a new execution scope

A fresh instance can show an empty catalog; the creation action is in the page header.

1. Select Create scope (New execution scope in some releases).
2. Open Infrastructure → Execution scopes.

Create a new execution scope

On a small screen, scroll sideways to inspect each control.

1. Select Create scope (New execution scope in some releases).
2. Open Infrastructure → Execution scopes.

1. Open Infrastructure → Execution scopes.
2. Select Create scope (called New execution scope in some releases).
3. Name it First local scope and select your local environment.
4. Leave Create the initial network topology enabled.
5. Select Create execution scope.

Name the scope and keep its topology

Enter First local scope. The initial topology is sufficient for a one-machine experiment.

1. Enter First local scope in Name.
2. Leave Create the initial network topology enabled.

Name the scope and keep its topology

On a small screen, scroll sideways to inspect each control.

1. Enter First local scope in Name.
2. Leave Create the initial network topology enabled.

Select only the local environment for this experiment

The reference instance calls its existing environment Local environment. In your tutorial, choose Local check.

1. Keep the initial topology enabled.
2. Select the checkbox for your local environment; use Local check from step 2.

Select only the local environment for this experiment

On a small screen, scroll sideways to inspect each control.

1. Keep the initial topology enabled.
2. Select the checkbox for your local environment; use Local check from step 2.

After selecting Local check, scroll to the bottom of the form to save it:

Save the execution scope

Scroll below the list of participating environments to reach this action.

1. Select Create execution scope after naming the scope and selecting Local check.

Save the execution scope

On a small screen, scroll sideways to inspect each control.

1. Select Create execution scope after naming the scope and selecting Local check.

A scope selects the environment resources offered to planning. Its topology describes the connections between them. A one-machine experiment needs no network links.

Desktop creates these records and their identifiers. The YAML here describes the workflow; you do not need to author environment, scope, or plan API envelopes.

6. Make a plan and start the run

Return to first-local-check and select Generate plan:

Start planning from the workflow

This reference definition is named hello. Open first-local-check in your own catalog.

1. Select Generate plan on the workflow detail page.

Start planning from the workflow

On a small screen, scroll sideways to inspect each control.

1. Select Generate plan on the workflow detail page.

Choose manual planning

The reference definition has two activities. Your first-local-check definition has only write-report.

1. Select Create manually.
2. Use Real execution.
3. Under Execution scope, choose First local scope; scroll the list if needed.

Choose manual planning

On a small screen, scroll sideways to inspect each control.

1. Select Create manually.
2. Use Real execution.
3. Under Execution scope, choose First local scope; scroll the list if needed.

1. Choose Create manually.
2. Select First local scope.
3. Select write-report in the activity graph.
4. Choose your local machine runtime and local machine resource.
5. Set Expected execution time to 1 second.
6. Select Generate plan.

Assign a runtime, duration, and target

This reference activity is named a. In your workflow, select write-report; configure the same controls.

1. Select the activity node in the DAG.
2. Choose the local machine runtime.
3. Set Expected execution time to 1 and keep the s unit.
4. Choose your local machine target. Then scroll to the plan review and Generate plan.

Assign a runtime, duration, and target

On a small screen, scroll sideways to inspect each control.

1. Select the activity node in the DAG.
2. Choose the local machine runtime.
3. Set Expected execution time to 1 and keep the s unit.
4. Choose your local machine target. Then scroll to the plan review and Generate plan.

The duration is an estimate, not a timeout or a measurement. Image download and startup can make the first run take longer.

On the saved plan page, select Execute plan:

Open the execution request from the saved plan

The example capture shows an existing saved plan. Use the manual plan generated for first-local-check.

1. Select Execute plan.

Open the execution request from the saved plan

On a small screen, scroll sideways to inspect each control.

1. Select Execute plan.

Review the selected plan, Real execution, and the local runtime. Keep the suggested unique run ID or enter your own:

Review the execution before starting

This reference plan is bound to its execution request. Your scope and plan names should refer to your new tutorial records.

1. Keep the suggested run ID or enter a fresh unique ID.
2. Confirm that the selected plan is the one you just generated.
3. Confirm Real execution and an available local runtime.

Review the execution before starting

On a small screen, scroll sideways to inspect each control.

1. Keep the suggested run ID or enter a fresh unique ID.
2. Confirm that the selected plan is the one you just generated.
3. Confirm Real execution and an available local runtime.

Scroll to the bottom, then select Start execution once:

Start the local run

Scroll to the bottom of the execution request after reviewing the selected plan.

1. Select Start execution once. Submission is asynchronous; wait on the resulting run page.

Start the local run

On a small screen, scroll sideways to inspect each control.

1. Select Start execution once. Submission is asynchronous; wait on the resulting run page.

Wait until the run says completed and 1/1 activities settled:

Check completion and open Activities

This real reference run has two activities. Your first-local-check run must show 1/1 settled.

1. Wait for completed.
2. Check 1/1 settled for your one-activity workflow.
3. Open Activities to locate write-report.

Check completion and open Activities

On a small screen, scroll sideways to inspect each control.

1. Wait for completed.
2. Check 1/1 settled for your one-activity workflow.
3. Open Activities to locate write-report.

A plan describes where work should run. A run records what happened. Submission is asynchronous: pending or running can appear before completed.

7. Inspect your first result

On the completed run, select Activities, then write-report. Open its Details link or Open activity page from its information panel (some releases label this Open activity details).

Locate the activity to inspect its output

This reference run lists a and b. Your activity list contains write-report.

1. Select write-report in your activity list. Use Details or Open activity page in its information panel.

Locate the activity to inspect its output

On a small screen, scroll sideways to inspect each control.

1. Select write-report in your activity list. Use Details or Open activity page in its information panel.

Where to look	Expected result
Execution details	Exit code 0
Activity output/log	Akoflow local check
Generated files	result.txt, with a SHA-256 checksum

Scroll down the activity page to Activity output and Generated files:

Find the output and its checksum

The reference run produced a.txt. Your YAML produces result.txt and prints Akoflow local check.

1. Inspect Activity output for the captured runtime log.
2. In Generated files, look for result.txt in your run.
3. Confirm that the file has a SHA-256 checksum.

Find the output and its checksum

On a small screen, scroll sideways to inspect each control.

1. Inspect Activity output for the captured runtime log.
2. In Generated files, look for result.txt in your run.
3. Confirm that the file has a SHA-256 checksum.

The generated file belongs to the activity workspace managed by the engine. Listing a file records that it was observed; it does not automatically download it into your computer's Downloads folder.

You have now submitted and inspected a real local experiment. Save the YAML with your experiment material so the definition can be reused.

8. Extend it into a small analysis

Save the next document as first-local-analysis.yaml, or download the complete analysis YAML. This is a new, complete workflow, with a different name from the first definition.

First local analysis. Nodes in the same column can run in parallel once their dependencies complete.

Activity	Reads	Produces
prepare	Values declared in its command: 2, 4, 6	measurements.txt
analyze	measurements.txt	mean.txt, containing 4.00
write-report	mean.txt	report.txt, containing Mean: 4.00

name: first-local-analysis
spec:
  namespace: learning
  activities:
    - name: prepare
      cpuLimit: "0.1"
      memoryLimit: 32Mi
      command:
        executable:
          source:
            type: oci
            reference: docker.io/library/busybox:1.36
          delivery:
            strategy: auto
            targetFormat: oci
        entrypoint: sh
        arguments:
          - -c
          - |
            printf '2\n4\n6\n' > measurements.txt
            cat measurements.txt
      expectedOutputs: [measurements.txt]

    - name: analyze
      dependsOn: [prepare]
      cpuLimit: "0.1"
      memoryLimit: 32Mi
      command:
        executable:
          source:
            type: oci
            reference: docker.io/library/busybox:1.36
          delivery:
            strategy: auto
            targetFormat: oci
        entrypoint: sh
        arguments:
          - -c
          - |
            awk '{sum += $1; n++} END {printf "%.2f\n", sum/n}' measurements.txt > mean.txt
            cat mean.txt
      expectedOutputs: [mean.txt]

    - name: write-report
      dependsOn: [analyze]
      cpuLimit: "0.1"
      memoryLimit: 32Mi
      command:
        executable:
          source:
            type: oci
            reference: docker.io/library/busybox:1.36
          delivery:
            strategy: auto
            targetFormat: oci
        entrypoint: sh
        arguments:
          - -c
          - |
            printf 'Mean: %s\n' "$(cat mean.txt)" > report.txt
            cat report.txt
      expectedOutputs: [report.txt]

The new field is dependsOn. analyze waits for prepare, and write-report waits for analyze. AkôFlow stages the predecessor's workspace before a dependent activity starts. Each stage writes a different output path, avoiding conflicting contents at the same path. expectedOutputs verifies that the required file exists.

Repeat the Desktop sequence:

1. Import first-local-analysis.yaml in Workflows → Definitions.
2. Confirm the three-node DAG above.
3. Create a manual plan using the existing First local scope.
4. Assign all three activities to the local runtime and resource, with an expected duration of 1 second each.
5. Generate the plan, choose Execute plan → Real execution, and start it.
6. Wait for completed and 3/3 activities settled.
7. Open the final write-report activity. Its log should print Mean: 4.00. Its generated files should include report.txt with a checksum.

This graph is sequential because each stage consumes the previous stage's output. A future independent branch should declare only the dependencies it needs. Dependencies determine readiness; resource capacity determines whether ready activities can run together.

If something stops you

Symptom	Next action
Desktop does not reach Connected	Check Docker and inspect first-start failure details.
Local environment is offline or missing from planning	Test its connection, save it, and select Check now.
YAML import fails	Check indentation, retain the complete name/spec wrapper, and use a distinct workflow name.
No compatible runtime appears	Recheck the environment's runtime binding and select a real local scope.
The first activity cannot obtain its image	Inspect the activity error and verify access to Docker Hub and the local Docker engine.
Analysis cannot find its input	Check dependsOn, the predecessor's completion, and workspace-staging evidence.
A run fails or stays pending	Open activity details and run events, then see Troubleshooting.

The idea behind AkôFlow

The original AkôFlow paper introduces middleware for parallel scientific workflows in containerized environments, with provenance capture and an astronomy evaluation. It gives the research context for the project:

Ferreira, W.; Kunstmann, L.; Paes, A.; Bedo, M.; de Oliveira, D. AkôFlow: um Middleware para execução de Workflows científicos em múltiplos ambientes conteinerizados. SBBD, 2024, pp. 27–39. Read the paper.

This post follows the current Desktop interface and portable workflow format, which have evolved since the publication. The paper explains the research motivation; the documentation and downloadable YAML files describe the steps used here.

Here, the YAML is the workflow definition, the environment is your local machine, the scope selects eligible resources, the plan assigns activities, and the run holds observed results. Generated files and checksums provide a first piece of execution evidence.

For your next experiment, change the measurements in a new copy of the analysis YAML and check that the mean changes accordingly. Continue with planning alternatives, workflow authoring, or the Montage 050 scientific workflow.

API automation is a separate next step once you know these objects; see API access. The Desktop path manages its internal credentials for you.