Keep workflow results on your machine¶

Run a simple workflow on your own Linux machine through AntFlow. It writes a text file into the launcher's mounted working directory, without declaring workflow outputs or uploading results or job logs.

Before you start¶

You need:

A Linux machine with Docker or rootless Podman installed, and network access to the AntFlow API and Docker Hub. For Docker, you need permission to use its socket.
An AntFlow account that can register a personal launcher.
A GitLab project you can edit, on the GitLab instance connected to AntFlow.
The AntFlow API URL.

The repository can remain private, but AntFlow must be able to read it through your account or the instance's published-project access. For Keycloak sign-in, configure your GitLab access if needed.

This is not an offline run

AntFlow still receives the submitted inputs, job status, and progress. This tutorial prevents automatic result and job-log uploads, not those exchanges. Do not include confidential information in the example input.

1. Create the workflow in GitLab¶

Open a project on your instance's GitLab, or create a blank project named antflow-local-results. Add a file named workflow.cwl with this content:

cwlVersion: v1.2
class: Workflow
id: local-results
label: Write a local text file
doc: Write a message on the local launcher without publishing result files.

inputs:
  message:
    type: string
    label: Message
    default: Hello from my local AntFlow launcher!

outputs: {}

steps:
  write-result:
    in:
      message: message
    out: []
    run:
      class: CommandLineTool
      baseCommand: printf
      stdout: local-result.txt
      requirements:
        DockerRequirement:
          dockerPull: alpine:3.22
      arguments:
        - "%s\n"
      inputs:
        message:
          type: string
          inputBinding:
            position: 1
      outputs: {}

Commit the file to your chosen branch, for example main. The last and only step runs printf '%s\n' "your message". The stdout setting writes its text to local-result.txt in the container's working directory, without declaring a CWL output. cwltool mounts that directory from the launcher's workdir on your machine.

The step and workflow declare no outputs. AntFlow therefore adds no automatic publication step: this example uploads no result files to S3 and creates no STAC catalog.

In the project's settings, add the discovery topic required by your AntFlow instance. The default is antflow; use the exact topic supplied by your administrator if the instance uses a different one.

2. Register your local launcher¶

Sign in to AntFlow.
Open your user profile, then Manage Launchers and New Launcher.
Name it my-local-results, choose an expiration date, and click Create.
Save the issued launcher token before closing the dialog.

The token below must be this launcher token, not your GitLab or user API token. Use this dedicated personal launcher for the exercise: its log and retention settings apply to every job it runs.

3. Prepare your machine¶

Keep using the same Bash terminal for the following commands:

mkdir -p "$HOME/antflow-local-results"
cd "$HOME/antflow-local-results"
WORKDIR="$PWD/workdir"
mkdir -p "$WORKDIR"

Create a .env file in this directory with the following content. Replace <launcher-token> with the token from step 2 and the example URL with your instance's full API URL:

APP_TOKEN=<launcher-token>
APP_API__URL=https://antflow.example.com/api
APP_ARCHIVE=false
APP_KEEP_WORKING_FOLDER=true
APP_CWLTOOL_EXTRA_ARGS=["--leave-tmpdir"]

Protect the file:

chmod 600 .env

These environment variables override the launcher's settings:

Variable	Why it is needed here
`APP_ARCHIVE=false`	Disable job-log uploads.
`APP_KEEP_WORKING_FOLDER=true`	Prevent the launcher from deleting the whole job directory.
`APP_CWLTOOL_EXTRA_ARGS=["--leave-tmpdir"]`	Prevent cwltool from deleting the step directories containing the undeclared result file.

The launcher and cwltool have separate cleanup mechanisms. These settings retain the job directory and temporary step output directories; cached step outputs are already excluded from cwltool's normal output cleanup. Files accumulate in the workdir until you remove them yourself.

4. Start the launcher¶

Select a compatible launcher version, then enter its image tag:

read -r -p "AntFlow Launcher image tag: " LAUNCHER_VERSION

Choose Docker or Rootless Podman below. If your docker command is provided by Podman, use the Podman instructions.

DockerRootless Podman

CONTAINER_RUNTIME=docker
docker run --detach --name antflow-launcher \
  --user "$(id -u):$(id -g)" \
  --group-add "$(stat -c '%g' /var/run/docker.sock)" \
  --env-file "$PWD/.env" \
  --env DOCKER_HOST=unix:///var/run/docker.sock \
  --env APP_WORKING_DIR="$WORKDIR" \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  --volume "$WORKDIR:$WORKDIR" \
  registry.gitlab.com/csgroup-oss/antflow/antflow-launcher:"$LAUNCHER_VERSION"

The additional group grants the launcher access to the Docker socket. Your host user must have permission to use that socket.

Start your user's Podman API socket:

systemctl --user start podman.socket

Start the launcher without sudo:

CONTAINER_RUNTIME=podman
PODMAN_SOCKET="${XDG_RUNTIME_DIR:-/run/user/$(id -u)}/podman/podman.sock"
podman run --detach --name antflow-launcher \
  --user 0:0 \
  --env-file "$PWD/.env" \
  --env DOCKER_HOST=unix:///var/run/docker.sock \
  --env APP_WORKING_DIR="$WORKDIR" \
  --volume "$PODMAN_SOCKET:/var/run/docker.sock" \
  --volume "$WORKDIR:$WORKDIR" \
  registry.gitlab.com/csgroup-oss/antflow/antflow-launcher:"$LAUNCHER_VERSION"

For SELinux socket-access restrictions or keeping the socket available after logout, see Rootless Podman.

Check startup¶

The workdir is mounted at the same absolute path on the host and in the launcher, so the host runtime can mount the step directories correctly. The launcher places them under the job directory because DOCKER_HOST is set.

Check startup locally:

"$CONTAINER_RUNTIME" logs --tail 50 antflow-launcher

Service messages remain visible through the container logs; disabling job-log uploads does not disable the launcher's own logging.

Runtime socket access

This launcher can start containers through your runtime socket. Only run workflows and container images you trust.

5. Run the workflow through AntFlow¶

In Processings, the first tab shown when you open AntFlow, click your GitLab project's card.
Select the branch containing workflow.cwl and open Write a local text file.
Keep the default message or enter your own non-sensitive text.
Select the my-local-results launcher and submit the job.
Wait for the job to finish successfully, then copy its job ID.

No published result files or uploaded job logs are expected in the job details. The file is on your machine; retrieve it in the next step.

6. Read the file on your machine¶

In the same terminal, enter the job ID copied from AntFlow:

read -r -p "AntFlow job ID: " JOB_ID
JOB_DIR="$WORKDIR/${JOB_ID//_/-}"
find "$JOB_DIR" -type f -name local-result.txt -print -exec cat {} \;

The command prints the file's path and, with the default input:

Hello from my local AntFlow launcher!

The command prints the exact path inside this job's directory, whether the step used cached or temporary output storage. Open that path in your file manager or text editor. The job ID's underscores are replaced by hyphens in directory names, which the command handles for you.

The file is not moved into the job's outputs directory because no CWL output was declared. It remains in the step directory, even after the launcher stops.

If something fails¶

The project or workflow is missing: check the GitLab instance, branch, discovery topic, and your repository access.
The launcher cannot start containers: check access to the socket for your selected runtime and whether Docker Hub is reachable.
The job fails: use its job ID in step 6 to set JOB_DIR, then read its local execution log:
```
tail -n 50 "$JOB_DIR/stderr.log"
```
The result file disappears: check both retention variables in .env. After changing them, recreate the launcher container so it loads the new values.

Stop the launcher¶

After the job has finished:

"$CONTAINER_RUNTIME" stop antflow-launcher
"$CONTAINER_RUNTIME" rm antflow-launcher

Your host workdir and its files remain. Retained job directories also contain inputs and logs; keep their access restricted and remove them when no longer needed. Delete or revoke the launcher registration when you no longer use it.

What's next¶

Workflows without declared outputs: result-publication behavior.
Local launcher: advanced runtime settings and troubleshooting.