### Install Client with Examples

Source: https://github.com/xflops/flame/blob/main/flmadm/README.md

Install the Flame client components along with all example binaries. This is useful for testing and demonstrating Flame's capabilities.

```bash
flmadm install --client --with-examples --prefix ~/flame
```

--------------------------------

### Deploy Candle-Based Example Service (Installed Environment)

Source: https://github.com/xflops/flame/blob/main/examples/candle/based/README.md

Deploys the candle-based example service using `flmctl` from an installed Flame environment. Ensure the Flame environment is sourced before running.

```bash
source /usr/local/flame/sbin/flmenv.sh
flmctl deploy \
  --name candle-based-example \
  --application /usr/local/flame/examples/candle/based/candle-based-example-service
```

--------------------------------

### Run Candle-Based Example Client from Installed Flame

Source: https://github.com/xflops/flame/blob/main/examples/candle/based/README.md

Execute the candle-based example client when Flame is installed. This command assumes the client binary is available in the system's PATH or specified by its full path.

```bash
/usr/local/flame/examples/candle/based/candle-based-example \
  --app candle-based-example \
  --prompt "The future of distributed inference is" \
  --sample-len 64 \
  --which 360m
```

--------------------------------

### Executable File Deployment Example

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE458-flmctl-deploy/FS.md

Example of deploying an application packaged as an executable file. The command infers the installer and command from the file.

```bash
flmctl deploy \
  --name candle-based-example \
  --application ./target/release/candle-based-example-service
```

```yaml
metadata:
  name: candle-based-example
spec:
  shim: Host
  command: candle-based-example-service
  installer: binary
  url: grpc://flame-object-cache:9090/candle-based-example/pkg/candle-based-example-953bf914bd839f80.tar.gz
```

--------------------------------

### Python Directory Deployment Example

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE458-flmctl-deploy/FS.md

Example of deploying a Python application from a directory. The command infers the installer and command from the directory contents.

```bash
flmctl deploy --name image-classifier --application .
```

```yaml
metadata:
  name: image-classifier
spec:
  shim: Host
  command: image-classifier
  installer: python
  url: grpc://flame-object-cache:9090/image-classifier/pkg/image-classifier-82e0f0d2d68f9341.tar.gz
```

--------------------------------

### Run Installed Client with Custom Prompt

Source: https://github.com/xflops/flame/blob/main/examples/candle/based/README.md

Execute the installed candle-based example client with a custom prompt. This demonstrates running inference with user-provided text after the service has been deployed.

```bash
root@bda125c204f6:/usr/local/flame# ./examples/candle/based/candle-based-example \
  --app candle-based-example \
  --prompt 'Flying monkeys are'
```

--------------------------------

### Install and Enable Services

Source: https://github.com/xflops/flame/blob/main/flmadm/README.md

Install all Flame components and immediately enable their systemd services. This ensures that Flame starts automatically on boot after installation.

```bash
sudo flmadm install --all --enable
```

--------------------------------

### Fresh System-Wide Flame Installation

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE333-flmadm/FS.md

Installs Flame system-wide, enabling services to start on boot. Requires root privileges.

```bash
sudo flmadm install --enable
```

--------------------------------

### Navigate to Example Directory

Source: https://github.com/xflops/flame/blob/main/examples/ps/README.md

Command to change the current directory to the parameter server example.

```bash
cd examples/ps
```

--------------------------------

### Quick Development Setup with TLS

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE234-tls/FS.md

Fastest path to TLS-enabled local development using `flmadm` to generate certificates and `flame-session-manager` to start with TLS configuration. Includes testing with `flmctl` both with and without CA verification.

```bash
# One-liner: generate certs and start with TLS
flmadm cert generate --output-dir /tmp/flame-certs --san "localhost,127.0.0.1"

# Start session manager with TLS
flame-session-manager --config - <<EOF
cluster:
  name: dev
  endpoint: "https://localhost:8080"
  storage: mem
  tls:
    cert_file: /tmp/flame-certs/server.crt
    key_file: /tmp/flame-certs/server.key
  executors:
    shim: host
EOF

# In another terminal, test with flmctl
flmctl --insecure list session
# Or with CA verification
flmctl --ca-cert /tmp/flame-certs/ca.crt list session

```

--------------------------------

### flmadm Install Process

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE333-flmadm/FS.md

Outlines the sequential phases involved in installing Flame using the flmadm CLI tool. This includes validation, preparation, building, installation, systemd setup, and verification.

```bash
┌─────────────────┐
│  flmadm install │
└────────┬────────┘
         │
         ├──► Phase 1: Validation
         │    - Check permissions
         │    - Validate paths
         │    - Check dependencies
         │
         ├──► Phase 2: Preparation
         │    - Clone/locate source
         │    - Create directories
         │    - Create flame user
         │
         ├──► Phase 3: Build
         │    - Build Rust binaries (including flmadm itself)
         │    - Prepare Python SDK
         │
         ├──► Phase 4: Installation
         │    - Copy binaries
         │    - Install Python SDK
         │    - Generate config files
         │
         ├──► Phase 5: Systemd Setup
         │    - Generate service files
         │    - Set permissions
         │    - Enable services (optional)
         │
         └──► Phase 6: Verification
              - Test binaries
              - Validate configuration
              - Report status
```

--------------------------------

### Invoke and Run Tasks

Source: https://github.com/xflops/flame/blob/main/sdk/python/README.md

Examples for running tasks synchronously, asynchronously, and in parallel. Also shows how to create, get, and watch task status.

```python
from concurrent.futures import wait

# Run a task synchronously (blocks until complete)
result = session.invoke(b"input data")

# Run a task asynchronously (returns Future immediately)
future = session.run(b"input data")
result = future.result()  # Wait for completion

# Run multiple tasks in parallelutures = [session.run(f"input {i}".encode()) for i in range(10)]
wait(futures)  # Wait for all tasks to complete
results = [f.result() for f in futures]

# Create a task and get task object
task = session.create_task(b"input data")

# Get task status
task = session.get_task(task.id)

# Watch task progress
for update in session.watch_task(task.id):
    print(f"Task state: {update.state}")
    if update.is_completed():
        break
```

--------------------------------

### Local Testing Commands

Source: https://github.com/xflops/flame/blob/main/CHANGELOG_FLMADM.md

Execute these commands to install, start, test, and clean up the local development environment.

```bash
# Local testing
./hack/local-test.sh install
./hack/local-test.sh start
./hack/local-test.sh test
./hack/local-test.sh clean
```

--------------------------------

### Distributed Cluster Setup - Client/User Host

Source: https://github.com/xflops/flame/blob/main/flmadm/README.md

Installs client utilities on a host for user access in a distributed environment, without running services.

```bash
# On client/jump host (for users)
flmadm install --client --prefix ~/flame --no-systemd
```

--------------------------------

### Clean Install with Backup and Enable

Source: https://github.com/xflops/flame/blob/main/flmadm/README.md

Perform a clean installation of Flame, backing up existing configurations and data before reinstalling. Services are enabled to start on boot.

```bash
sudo flmadm install --all --clean --enable
```

--------------------------------

### Example Client Output

Source: https://github.com/xflops/flame/blob/main/examples/agents/openai/README.md

This is the expected output when running the client script to interact with the OpenAI agent. It shows the virtual environment setup and the agent's initial greeting.

```bash
# uv run client.py -m "What is the weather like in Seattle?"
Using CPython 3.12.3 interpreter at: /usr/bin/python3.12
Creating virtual environment at: .venv
Downloading setuptools (1.1MiB)
Downloading grpcio (6.1MiB)
Downloading cryptography (4.1MiB)
Downloading grpcio-tools (2.5MiB)
Downloading pydantic-core (1.8MiB)
 Downloading setuptools
 Downloading pydantic-core
 Downloading grpcio-tools
 Downloading cryptography
 Downloading grpcio
warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance.
         If the cache and target directories are on different filesystems, hardlinking may not be supported.
         If this is intentional, set `export UV_LINK_MODE=copy` or use `--link-mode=copy` to suppress this warning.
Installed 49 packages in 2.20s
Hello! I'm your AI weather forecaster assistant. I'm here to provide you with weather-related information, forecasts, climate insights, and tips to help you plan your day or understand weather patterns. Whether you need current conditions, a forecast for your location, or explanations about meteorological phenomena, I'm here to help! How can I assist you today?
```

--------------------------------

### Fish Shell Completion Installation

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE375-codebase-enhancements/FS.md

Example command to install Fish shell completion scripts for `flmctl`. This command redirects the output of `flmctl completion fish` to the Fish completions directory.

```bash
# Fish
flmctl completion fish > ~/.config/fish/completions/flmctl.fish
```

--------------------------------

### Runner Constructor Example

Source: https://github.com/xflops/flame/blob/main/docs/tutorials/runner-setup.md

Demonstrates how to instantiate a Runner with a name and optionally configure fail_if_exists. This snippet shows the basic setup for using the Runner.

```python
Runner(name: str, fail_if_exists: bool = False)
```

--------------------------------

### Clone Repository and Install SDK

Source: https://github.com/xflops/flame/blob/main/sdk/python/README.md

Steps to clone the Flame repository and install the Python SDK in development mode or build and install the wheel.

```bash
# Clone the repository
git clone https://github.com/xflops/flame.git
cd flame/sdk/python

# Install in development mode
# Note: Use --no-build-isolation if you have setuptools>=61.0 installed
python3 -m pip install -e . --user --no-build-isolation

# Or build and install the wheel
python3 -m build --wheel --no-isolation
python3 -m pip install dist/flamepy-0.6.0-py3-none-any.whl --user

# Install development dependencies
pip install -e .[dev]

# Run tests
pytest

# Format code
ruff format

# Type checking
mypy flamepy/
```

--------------------------------

### Install, Start, Test, and Clean Up with flmadm Local Test Script

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE333-flmadm/INTEGRATION.md

Commands to manage a local cluster using the `local-test.sh` script for faster development cycles.

```bash
# Install and start cluster
./hack/local-test.sh install
./hack/local-test.sh start

# Run tests
./hack/local-test.sh test

# Stop and cleanup
./hack/local-test.sh clean
```

--------------------------------

### Rust App Installation Algorithm

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE420-app-installer/FS.md

This Rust function outlines the core algorithm for installing an application. It handles checking for existing installations, downloading, extracting, and executing the installer, including error handling and state management.

```rust
pub async fn install(&self, app: &ApplicationContext) -> Result<HashMap<String, String>, FlameError> {
    // 0. Skip if no installer configured (WASM apps, pre-installed apps)
    let installer_type = match &app.installer {
        None => {
            tracing::debug!("No installer configured for app <{}>, skipping", app.name);
            return Ok(HashMap::new());
        }
        Some(installer_str) => installer_str.parse::<InstallerType>()?,
    };
    
    // 1. Fast path: check if already installed
    {
        let apps = lock_ptr!(self.apps)?;
        if let Some(installed) = apps.get(&app.name) {
            let installed = installed.read().await;
            if installed.state == InstallState::Installed {
                return Ok(installed.env_vars.clone());
            }
        }
    }
    
    // 2. Acquire or create per-app entry
    let app_entry = {
        let mut apps = lock_ptr!(self.apps)?;
        apps.entry(app.name.clone())
            .or_insert_with(|| Arc::new(RwLock::new(AppInstaller::new(&app.name, installer_type.clone()))))
            .clone()
    };
    
    // 3. Acquire write lock (blocks concurrent installers)
    let mut installed = app_entry.write().await;
    
    // 4. Double-check after acquiring lock
    if installed.state == InstallState::Installed {
        return Ok(installed.env_vars.clone());
    }
    
    if let InstallState::Failed(msg) = &installed.state {
        return Err(FlameError::Internal(msg.clone()));
    }
    
    // 5. Mark as installing
    installed.state = InstallState::Installing;
    
    // 6. Download package from url
    let url = app.url.as_ref()
        .ok_or_else(|| FlameError::InvalidConfig("installer requires url".to_string()))?;
    let package_path = self.download_package(url, &app.name).await?;
    
    // 7. Extract archive
    let src_path = self.flame_home.join("data/apps").join(&app.name).join("src");
    self.extract_package(&package_path, &src_path)?;
    
    // 8. Create installer and run installation via trait
    let installer = installer_type.create_installer();
    tracing::info!("Running {} installer for app <{}>", installer.name(), app.name);
    let env_vars = installer.install(&app.name, &src_path, &self.flame_home).await?;
    
    // 9. Update state
    installed.state = InstallState::Installed;
    installed.install_path = src_path;
    installed.env_vars = env_vars.clone();
    installed.installed_at = Some(Utc::now());
    
    Ok(env_vars)
}
```

--------------------------------

### Build and Install flmadm

Source: https://github.com/xflops/flame/blob/main/README.md

Builds the `flmadm` tool from source and installs it globally. Requires Rust and uv. Ensure you have the necessary permissions for global installation.

```shell
# Build and install flmadm
$ cargo build --release -p flmadm
$ sudo install -m 755 target/release/flmadm /usr/local/bin/
```

--------------------------------

### Access Flame Console and Navigate to Example

Source: https://github.com/xflops/flame/blob/main/examples/pi/python/README.md

Logs into the Flame console container and navigates to the Python Pi example directory. This is necessary to execute the example script.

```shell
[klausm@flm-worker flame]$ docker compose exec -it flame-console /bin/bash
root@0e24c41da5f5:/# cd /opt/examples/pi/python/
root@0e24c41da5f5:/opt/examples/pi/python# ls
README.md  main.py  pyproject.toml
```

--------------------------------

### Initial Development Setup

Source: https://github.com/xflops/flame/blob/main/CHANGELOG_FLMADM.md

Run this command once to set up the development environment.

```bash
make install-dev
```

--------------------------------

### New Local Development Workflow: Install

Source: https://github.com/xflops/flame/blob/main/CHANGELOG_FLMADM.md

Install development dependencies and set up the local environment using the new script.

```bash
./hack/local-test.sh install
```

--------------------------------

### Distributed Cluster Setup - Control Plane

Source: https://github.com/xflops/flame/blob/main/flmadm/README.md

Installs the control plane on the designated control node in a distributed setup.

```bash
# On control plane node (control01)
sudo flmadm install --control-plane --enable
```

--------------------------------

### Quick Start: Create and Invoke Session

Source: https://github.com/xflops/flame/blob/main/sdk/python/README.md

Demonstrates creating a session with an application and invoking a task.

```python
import flamepy

def main():
    # Create a session with the application, e.g. Agent
    session = flamepy.create_session("flmping")
    
    # Create and run a task
    resp = session.invoke(b"task input data")

    # Handle the output of task
    print(resp)

    # Close session
    session.close()

if __name__ == "__main__":
    main()
```

--------------------------------

### Basic Flame Installation

Source: https://github.com/xflops/flame/blob/main/flmadm/README.md

Perform a basic installation of all Flame components using flmadm. This command assumes a standard system setup and installs all necessary parts of the Flame cluster.

```bash
sudo flmadm install --all
```

--------------------------------

### Fairshare Algorithm Example Walkthrough

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE408-fairshare-batch-size/FS.md

This walkthrough demonstrates the batch-aligned fair distribution algorithm with a specific example. It shows the state of sessions and remaining slots through multiple iterations of allocation.

```pseudocode
Initial state:
  Session A: batch_size=4, slots=1, desired=8, min=0
  Session B: batch_size=1, slots=1, desired=4, min=0
  Cluster capacity: 10 slots

Iteration 1: Pop A (deserved=0)
  batch_unit=4, remaining=10 >= 4 ✓
  A.deserved = 4, remaining = 6
  Push A back

Iteration 2: Pop B (deserved=0)
  batch_unit=1, B.deserved = 1, remaining = 5
  Push B back

Iteration 3-5: B receives 3 more slots
  B.deserved = 4, remaining = 2
  B satisfied, not pushed back

Iteration 6: Pop A (deserved=4)
  batch_unit=4, remaining=2 < 4 ✗
  Skip (cannot fit another batch)

Final state:
  Session A: deserved=4 (1 complete batch)
  Session B: deserved=4 (4 executors)
  Unused: 2 slots (cannot form a batch for A, B is satisfied)
```

--------------------------------

### Run Candle-Based Example Client from Source

Source: https://github.com/xflops/flame/blob/main/examples/candle/based/README.md

Execute the candle-based example client directly from a source checkout using Cargo. Ensure you specify the application name, prompt, and sample length.

```bash
cargo run -p candle-based-example --bin candle-based-example --release -- \
  --app candle-based-example \
  --prompt "The future of distributed inference is" \
  --sample-len 64 \
  --which 360m
```

--------------------------------

### Combined Control Plane and Worker Installation

Source: https://github.com/xflops/flame/blob/main/flmadm/README.md

Install both the control plane and worker components on the same node. Services are enabled to start automatically.

```bash
sudo flmadm install --control-plane --worker --enable
```

--------------------------------

### Custom Path Flame Installation

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE333-flmadm/FS.md

Installs Flame to a custom directory, enabling services to start on boot. Requires root privileges.

```bash
sudo flmadm install --prefix /opt/flame --enable
```

--------------------------------

### Multi-Application Deployment Example

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE280-runner/runner-working-directory-change.md

Shows how to deploy multiple applications using the Runner service, ensuring no file conflicts between their working directories.

```python
# Application 1
with Runner("app1") as rr1:
    # Runs in /opt/app1/
    service1 = rr1.service(Service1())

# Application 2
with Runner("app2") as rr2:
    # Runs in /opt/app2/
    service2 = rr2.service(Service2())
    
# No file conflicts between applications
```

--------------------------------

### Install Flame Cluster

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE333-flmadm/FS.md

Installs the Flame cluster. Use --src-dir to specify a local source, --prefix for a custom installation directory, and --enable to start services after installation. Requires root privileges for systemd integration.

```bash
sudo flmadm install
```

```bash
sudo flmadm install --src-dir /path/to/flame
```

```bash
sudo flmadm install --prefix /opt/flame
```

```bash
sudo flmadm install --enable
```

```bash
flmadm install --no-systemd --prefix ~/flame
```

```bash
sudo flmadm install --clean --enable
```

```bash
sudo flmadm install --verbose
```

--------------------------------

### Tarball Deployment with Overrides Example

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE458-flmctl-deploy/FS.md

Example of deploying an application from a tarball, explicitly overriding the detected installer and command. This is useful when auto-detection is insufficient or incorrect.

```bash
flmctl deploy \
  --name image-classifier \
  --application ./dist/image-classifier.tar.gz \
  --installer python \
  --command python \
  --argument -m \
  --argument image_classifier.service
```

--------------------------------

### Enhanced setup() for Batch Allocation

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE408-fairshare-batch-size/FS.md

Implements the setup method for the FairShare plugin, modifying the allocation logic to distribute resources in batch units. Ensures desired allocation is batch-aligned and capped by max_instances, while respecting min_instances.

```rust
impl Plugin for FairShare {
    fn setup(&mut self, ss: &SnapShot) -> Result<(), FlameError> {
        // ... existing session initialization ...

        for ssn in open_ssns.values() {
            let batch_size = ssn.batch_size.max(1);

            // Frontend validates: min_instances and max_instances are batch-aligned

            // Calculate desired (batch-aligned from existing code)
            let batched_tasks = (task_count / batch_size as f64).floor() * batch_size as f64;
            let mut desired = batched_tasks * ssn.slots as f64;

            // Cap desired by max_instances
            if let Some(max) = ssn.max_instances {
                desired = desired.min((max * ssn.slots) as f64);
            }

            // Ensure desired is at least min_instances × slots
            let min_allocation = (ssn.min_instances * ssn.slots) as f64;
            desired = desired.max(min_allocation);

            self.ssn_map.insert(
                ssn.id.clone(),
                SSNInfo {
                    id: ssn.id.clone(),
                    desired,
                    deserved: min_allocation,
                    slots: ssn.slots,
                    min_instances: ssn.min_instances,
                    max_instances: ssn.max_instances,
                    batch_size,
                    ..SSNInfo::default()
                },
            );
        }

        // ... existing node and executor initialization ...

        // ENHANCED: Fair distribution in batch units
        let mut underused = BinaryHeap::from_iter(self.ssn_map.values_mut());
        loop {
            if remaining_slots < 0.001 {
                break;
            }

            if underused.is_empty() {
                break;
            }

            let ssn = underused.pop().expect("checked non-empty above");

            // Distribute in batch units
            let batch_unit = (ssn.batch_size * ssn.slots) as f64;

            // Skip if session already has its desired allocation
            if ssn.deserved >= ssn.desired {
                continue;
            }

            // Skip if not enough remaining slots for one batch unit
            if remaining_slots < batch_unit {
                continue;
            }

            // Allocate one batch unit
            let allocation = batch_unit.min(ssn.desired - ssn.deserved);
            ssn.deserved += allocation;
            remaining_slots -= allocation;

            // Re-add to heap if still underused
            if ssn.deserved < ssn.desired {
                underused.push(ssn);
            }
        }

        Ok(())
    }
}

```

--------------------------------

### Deploying an executable binary

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE458-flmctl-deploy/FS.md

Example of deploying an executable binary file using `flmctl deploy`. The command uploads the binary and registers it.

```bash
flmctl deploy \
  --name candle-based-example \
  --application ./target/release/candle-based-example-service
```

--------------------------------

### Install Flame with Worker and Cache Profiles

Source: https://github.com/xflops/flame/blob/main/flmadm/README.md

Installs Flame with worker and cache components, enabling systemd services. This is a typical setup for worker nodes.

```bash
sudo flmadm install --worker --cache --enable
```

--------------------------------

### New Local Development Workflow: Start

Source: https://github.com/xflops/flame/blob/main/CHANGELOG_FLMADM.md

Start the FLMADM services locally using the new script.

```bash
./hack/local-test.sh start
```

--------------------------------

### Run Parameter Server Example

Source: https://github.com/xflops/flame/blob/main/examples/ps/README.md

Command to execute the main Python script for the parameter server example.

```bash
python main.py
```

--------------------------------

### Start Flame Cluster with Docker Compose

Source: https://github.com/xflops/flame/blob/main/README.md

Use this command to start a local Flame cluster using Docker Compose. Ensure Docker Compose is installed.

```shell
$ docker compose up -d
```

--------------------------------

### Initialize Python Project with uv

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE280-runner/RFE280-runner.md

Use this command to set up a new Python project. Ensure uv is installed and available in your PATH.

```shell
uv init .
```

--------------------------------

### Install Flame Helm Chart with Multiple Object Cache Replicas

Source: https://github.com/xflops/flame/blob/main/charts/flame/README.md

Install the Flame Helm chart with a specified number of object-cache replicas. This example sets it to 3 replicas.

```bash
helm install flame ./charts/flame \
  --namespace flame \
  --create-namespace \
  --set objectCache.replicas=3
```

--------------------------------

### Run vLLM Example

Source: https://github.com/xflops/flame/blob/main/examples/vllm/README.md

Navigate to the example directory and execute the main Python script using 'uv run'. This script loads a small model for testing vLLM dependencies and runtime configuration.

```bash
cd /opt/examples/vllm
uv run main.py
```

--------------------------------

### View Application with Installer Config via flmctl

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE420-app-installer/FS.md

Use the 'flmctl get app' command with the '-o yaml' flag to view the configuration of an application, including its installer settings.

```bash
# View application with installer config
flmctl get app my-app -o yaml
```

--------------------------------

### flmctl create Usage Examples

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE413-priority-scheduling/FS.md

Demonstrates creating sessions with different priority levels using the 'flmctl create' command.

```bash
# Create a high-priority production session
flmctl create --app llm-inference --resreq cpu=4,mem=16g,gpu=1 --priority 100

# Create a medium-priority training session
flmctl create --app model-training --resreq cpu=8,mem=32g,gpu=2 --priority 50

# Create a low-priority batch session (default priority; resreq from cluster default)
flmctl create --app data-preprocessing

# Combine priority with batch/gang scheduling
flmctl create --app llm-inference --resreq cpu=4,mem=16g,gpu=1 --batch-size 4 --priority 100
```

--------------------------------

### Run Basic RL Example

Source: https://github.com/xflops/flame/blob/main/examples/rl/basic/README.md

Log into the Flame console and navigate to the example directory to run the main training script.

```shell
docker compose exec -it flame-console /bin/bash
root@container:/# cd /opt/examples/rl/basic
root@container:/opt/examples/rl/basic# uv run main.py
```

--------------------------------

### Bash Shell Completion Installation

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE375-codebase-enhancements/FS.md

Example command to install Bash shell completion scripts for `flmctl`. This command redirects the output of `flmctl completion bash` to the appropriate directory for Bash to load.

```bash
# Bash
flmctl completion bash > /etc/bash_completion.d/flmctl
```

--------------------------------

### Zsh Shell Completion Installation

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE375-codebase-enhancements/FS.md

Example command to install Zsh shell completion scripts for `flmctl`. This command redirects the output of `flmctl completion zsh` to the user's Zsh function directory.

```bash
# Zsh
flmctl completion zsh > ~/.zfunc/_flmctl
```

--------------------------------

### Access Flame Console and Navigate to Example

Source: https://github.com/xflops/flame/blob/main/examples/agents/openai/README.md

Log into the Flame console container and navigate to the example directory to run the agent.

```bash
docker exec -it flame_flame-console_1 /bin/bash
cd /opt/examples/agents/openai/
```

--------------------------------

### FlameInstance Entrypoint Example

Source: https://github.com/xflops/flame/blob/main/e2e/QUICK_REFERENCE.md

Demonstrates a simple decorator-based approach for defining an entrypoint using FlameInstance. Suitable for basic request/response services.

```python
# Simple decorator-based approach
instance = flamepy.FlameInstance()

@instance.entrypoint
def e2e_service_entrypoint(req: TestRequest) -> TestResponse:
    return TestResponse(output=req.input, common_data=...)

if __name__ == "__main__":
    instance.run()
```

--------------------------------

### Distributed Cluster Setup - Worker Nodes

Source: https://github.com/xflops/flame/blob/main/flmadm/README.md

Installs the worker components on worker nodes in a distributed cluster.

```bash
# On worker nodes (worker01, worker02, ...)
sudo flmadm install --worker --enable
```

--------------------------------

### CLI Command Example

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE234-tls/FS.md

Example of using the `flmctl` CLI tool to list sessions, with TLS enabled automatically when the endpoint and configuration are set up.

```bash
# Connect with TLS (automatic when endpoint uses https:// and tls config present)
flmctl --config ~/.flame/flame.yaml list session

```

--------------------------------

### Runner Auto-handling of Archive Packages

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE284-flmrun/runpy-enhancements.md

Notes on how FlameRunpyService automatically detects, extracts, and installs archive packages when a session starts.

```python
# Upload package to /opt/flame/packages/my-package.tar.gz
# Runner will automatically create the tar.gz

# When session starts, FlameRunpyService will:
# 1. Detect it's an archive
# 2. Extract to working directory
# 3. Install from extracted directory
```

--------------------------------

### Verify Application View and Startup Logs

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE368-shim-config/TEST_PLAN.md

Check the application details using the `view` command and verify that the startup logs for the executor-manager display the shim type.

```bash
# Verify view command (TC-012, TC-014)
flmctl view application test-app-no-shim
```

```bash
# Verify startup logs show shim type (TC-023)
docker logs flame-executor-manager 2>&1 | grep -i "shim"
```

--------------------------------

### Creating and Setting Permissions for /opt/

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE280-runner/runner-working-directory-change.md

This bash snippet demonstrates how to create the /opt/ directory if it does not exist and set its ownership and permissions. It includes options for secure ownership or less secure world-writable permissions.

```bash
sudo mkdir -p /opt
sudo chown $(whoami):$(whoami) /opt
# Or make it world-writable (less secure):
sudo chmod 777 /opt
```

--------------------------------

### Build Candle-Based Example Service

Source: https://github.com/xflops/flame/blob/main/examples/candle/based/README.md

Builds the candle-based example project from source using Cargo. This command generates the service binary and the main executable.

```bash
cargo build -p candle-based-example --release
```

--------------------------------

### Debug Flame Build Failure with Verbose Output

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE333-flmadm/FS.md

Rerun the installation with the --verbose flag to get detailed output for debugging build failures.

```bash
sudo flmadm install
```

```bash
sudo flmadm install --verbose
```

--------------------------------

### User-Written Service Binary Entrypoint

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE455-simplify-flame-rs-api/FS.md

Example of how a user explicitly writes the service binary entrypoint using `#[tokio::main]` to run the Flame.rs service.

```rust
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    flame_rs::run(ping).await
}
```

--------------------------------

### flmctl create Command Usage Examples

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE433-gpu-drf/FS.md

Demonstrates various ways to use the 'flmctl create' command with the '--resreq' flag, including examples with 'mem', 'memory', CPU-only workloads, and cases where the server applies default resources.

```bash
# Using explicit resources (mem)
flmctl create --app llm-inference --resreq "cpu=16,mem=64g,gpu=4"

# Using explicit resources (memory)
flmctl create --app llm-inference --resreq "cpu=16,memory=64g,gpu=4"

# CPU-only workload with explicit resources
flmctl create --app data-preprocess --resreq "cpu=8,mem=32g"

# No --resreq: server applies cluster.resreq, or the hardcoded fallback
flmctl create --app myapp
```

--------------------------------

### Manual Object Storage and Retrieval with Python SDK

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE318-cache/IMPLEMENTATION.md

Demonstrates how to use the `flamepy` SDK to store (put) and retrieve (get) objects from the cache. Requires `flamepy` to be installed.

```python
import flamepy
from flamepy.core import put_object, get_object

# Put an object
data = {"test": "data", "value": 123}
ref = put_object("test-session", data)
print(f"Stored: {ref.key} at {ref.endpoint}")

# Get the object
retrieved = get_object(ref)
assert retrieved == data
```

--------------------------------

### Deploy Candle-Based Example Service with flmctl

Source: https://github.com/xflops/flame/blob/main/examples/candle/based/README.md

Deploy the candle-based example service using the `flmctl deploy` command. This registers the application with Flame and specifies the service binary location.

```bash
root@bda125c204f6:/usr/local/flame# flmctl deploy \
  --name candle-based-example \
  --application ./examples/candle/based/candle-based-example-service
```

--------------------------------

### Runner API Usage Example (No Changes)

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE284-flmrun/runpy-enhancement-summary.md

Demonstrates that existing Runner API usage remains compatible with the enhancements. The `get()` method on the result automatically handles ObjectRef.

```python
# This still works exactly the same
with Runner("my-app") as rr:
    service = rr.service(MyClass())
    result = service.method()
    value = result.get()  # Handles ObjectRef automatically
```

--------------------------------

### Systemctl Commands for Flame Object Cache Management

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE426-cache-versioning/FS.md

Standard systemctl commands to manage the flame-object-cache service after installation. These commands allow starting, stopping, and checking the status of the cache service.

```bash
sudo systemctl start flame-object-cache
sudo systemctl stop flame-object-cache
sudo systemctl status flame-object-cache
```

--------------------------------

### Entrypoint Macro Example

Source: https://github.com/xflops/flame/blob/main/docs/designs/RFE455-simplify-flame-rs-api/FS.md

An example demonstrating how to define a typed entrypoint function for a Flame RS service using the `#[flame_rs::entrypoint]` macro.

```APIDOC
## Entrypoint Macro Example

### Description
This example shows a simple stateless service entrypoint that accepts an optional typed request and returns a typed response.

### Function Signature
`async fn ping(req: Option<PingRequest>) -> Result<PingResponse, FlameError>`

### Parameters
- `req` (Option<PingRequest>): An optional request object conforming to `FlameMessage`.

### Response
- `Result<PingResponse, FlameError>`: A result containing either a `PingResponse` object or a `FlameError`.

### Request Body Example
```rust
{
  "duration": 1000
}
```

### Response Example
```rust
{
  "message": "duration=Some(1000)"
}
```

### Usage
```rust
use flame_rs::apis::FlameError;

#[derive(Default, serde::Serialize, serde::Deserialize, flame_rs::FlameMessage)]
struct PingRequest {
    duration: Option<u64>,
}

#[derive(serde::Serialize, serde::Deserialize, flame_rs::FlameMessage)]
struct PingResponse {
    message: String,
}

#[flame_rs::entrypoint]
async fn ping(req: Option<PingRequest>) -> Result<PingResponse, FlameError> {
    let req = req.unwrap_or_default();
    Ok(PingResponse {
        message: format!("duration={{:?}}", req.duration),
    })
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    flame_rs::run(ping).await
}
```
```