User Guide

Use flmctl, register applications, configure clients, and operate Flame sessions.

Flame User Guide

This guide covers day-to-day Flame usage after a cluster is running.

CLI Tools

Flame has two primary command-line tools:

  • flmctl: user-facing CLI for applications, sessions, tasks, executors, and nodes.
  • flmadm: administrator CLI for installation, service setup, upgrades, and uninstall.

List Cluster Objects

flmctl list --application
flmctl list --session
flmctl list --executor
flmctl list --node

Short flags are also supported:

flmctl list -a
flmctl list -s
flmctl list -e
flmctl list -n

View Details

flmctl view --application flmping
flmctl view --session <session-id>
flmctl view --task <task-id>
flmctl view --node <node-name>

Use --output-format yaml when you need structured output.

Create and Close Sessions

Create a session for a registered application:

flmctl create --app flmping --batch-size 1 --priority 0

Pass a resource request when the workload needs explicit resources:

flmctl create --app flmping --resreq cpu=1,mem=1g

Close a session:

flmctl close --session <session-id>

Deploy Applications

flmctl deploy packages a local application, uploads it to the configured Flame object cache, and registers it with the session manager. Configure both endpoints as described below, and ensure executors can reach the object cache. For example, deploy a Python project directory:

flmctl deploy --name agent-app --application ./agent-app --dry-run -o yaml
flmctl deploy --name agent-app --application ./agent-app
flmctl view --application agent-app

The dry run prints the deployment plan without uploading or registering it. Deploy also accepts a standalone file or a .tar.gz/.tgz archive. For a directory, it detects a Python project or executable and its launch command; use --command and repeatable --argument options when detection does not provide the right command. A standalone .py file runs with python3 and does not install project dependencies, so those dependencies must be present on the executors.

A project directory can specify deployment defaults in flame.yaml or flm.yaml:

metadata:
  name: agent-app
spec:
  installer: python
  command: python3
  arguments: [-m, agent_app]

With this profile, flmctl deploy --application ./agent-app uses its application name and runtime settings. Explicit CLI options override profile fields; repeat --env NAME=VALUE to set environment variables. Add .flameignore or .flmignore to exclude files from a directory package. See flmctl deploy --help for all options, including runtime image and shim settings.

For a complete Python service and client example, see the flamepy.serving guide. Applications can also be registered directly from an existing YAML manifest:

Register Applications

Register an application from YAML:

flmctl register --file app.yaml

Update or unregister it:

flmctl update --application app.yaml
flmctl unregister --application <app-name>

Most Python users should start with flamepy.app, which packages the current project and registers an application for task-oriented Python code. Rust users can use flame-rs for native clients and service binaries.

Client Configuration

Use environment variables for simple local clients:

export FLAME_ENDPOINT=http://127.0.0.1:8080
export FLAME_CACHE_ENDPOINT=grpc://127.0.0.1:9090

Use ~/.flame/flame.yaml for persistent context-based configuration:

---
current-context: flame
contexts:
  - name: flame
    cluster:
      endpoint: "http://127.0.0.1:8080"
    cache:
      endpoint: "grpc://127.0.0.1:9090"

Cluster Configuration

Installed clusters use:

/usr/local/flame/conf/flame-cluster.yaml

Important fields include:

  • cluster.endpoint: session manager endpoint.
  • cluster.resreq: default task resource request.
  • cluster.policies: scheduler policy list.
  • cluster.executors.shims: enabled executor shims, for example [host].
  • cache.endpoint: object cache endpoint.
  • cache.storage: object cache storage path.

Restart Flame services after changing cluster configuration.

Troubleshooting

Services do not start:

sudo systemctl status flame-session-manager
sudo systemctl status flame-executor-manager
sudo systemctl status flame-object-cache
sudo journalctl -u flame-session-manager -n 50

Client cannot connect:

flmping
flmctl list --application

Then verify FLAME_ENDPOINT, FLAME_CACHE_ENDPOINT, and network access to ports 8080 and 9090.

App cannot start services:

flmctl list --application

Confirm the flmrun template appears. If not, check that the session manager started with the expected installation prefix and configuration.