Skip to content

fix: update README for new impl. #438

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
k82cn merged 2 commits into from
May 8, 2026
Merged

fix: update README for new impl. #438

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
acdc4d6
fix: update README for new impl.
k82cn May 8, 2026
2e16b81
fix: address PR review comments for README
k82cn May 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 67 additions & 42 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,28 @@ As Agentic AI become increasingly adopted for innovation, a common workload runt
* **Security**: Flame utilizes microVM as a runtime for enhanced security, with each runtime environment (executor) dedicated to a single session to prevent data leakage. All Flame components communicate using mTLS for secure inter-component communication.
* **Flexibility**: Flame defines a comprehensive set of general APIs to support multiple user scenarios. Additionally, Flame supports applications across multiple programming languages through gRPC, including Rust, Go, and Python.

## Performance

Flame is designed for high-throughput task execution. Here's a benchmark running 30,000 tasks on a single-node deployment:

```shell
root@06383dd94875:/# flmping -p -t 30000
Session <flmping-1N1sIX> was created in <1 ms>, start to run <30,000> tasks in the session:

============================================================
BENCHMARK RESULTS
============================================================
Duration: 3.29s
Succeeded: 30000/30000
Failed: 0
Throughput: 9124.09 tasks/sec
============================================================

root@06383dd94875:/# flmctl list -s
ID State App Slots Priority Pending Running Succeed Failed Created
flmping-1N1sIX Closed flmping 1 0 0 0 30000 0 18:11:26
```

## Architecture Overview

![Flame Architecture](docs/images/flame-arch.jpg)
Expand Down Expand Up @@ -59,51 +81,54 @@ After the Flame cluster is launched, use the following steps to log into the `fl
$ docker compose exec flame-console /bin/bash
```

### Option 2: Local Installation (Faster for Development)
### Option 2: Local Installation with flmadm (Faster for Development)

For development and testing, you can install Flame directly on your machine using `flmadm`:
For development and testing, you can install Flame directly on your machine using `flmadm` (requires [Rust](https://rustup.rs/) and [uv](https://astral.sh/uv)):

```shell
# Quick start with helper script
$ ./hack/local-test.sh install
$ ./hack/local-test.sh start

# Or using Make
$ make install-dev
$ /tmp/flame-dev/bin/flame-session-manager --config /tmp/flame-dev/conf/flame-cluster.yaml &
$ /tmp/flame-dev/bin/flame-executor-manager --config /tmp/flame-dev/conf/flame-cluster.yaml &
# Build and install flmadm
$ cargo build --release -p flmadm
$ sudo install -m 755 target/release/flmadm /usr/local/bin/

# Install all components from local source and start services
$ sudo flmadm install --all --src-dir . --enable
Comment on lines +93 to +94
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

After running flmadm install, the Flame binaries (such as flmping and flmctl) are installed to /usr/local/flame/bin by default. To use them in the current shell session, users need to source the generated environment script or manually update their PATH. Adding this step to the Quick Start guide will prevent "command not found" errors in the subsequent verification step.

Suggested change
# Install all components from local source and start services
$ sudo flmadm install --all --src-dir . --enable
# Install all components from local source and start services
$ sudo flmadm install --all --src-dir . --enable
$ source /usr/local/flame/sbin/flmenv.sh

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The flmadm install command with the --all flag (or --worker/--client) requires uv to be installed on the host system, as enforced in flmadm/src/commands/install.rs. Since this is a 'Quick Start' guide, it would be helpful to mention this prerequisite here to prevent users from encountering a validation error during their first installation attempt.

Suggested change
$ sudo flmadm install --all --src-dir . --enable
# Ensure uv is installed (e.g., curl -LsSf https://astral.sh/uv/install.sh | sh)
$ sudo flmadm install --all --src-dir . --enable


# Add Flame binaries to PATH
$ source /usr/local/flame/sbin/flmenv.sh
```

For more details, see the [Local Development Guide](docs/tutorials/local-development.md).
For more details, see the [flmadm README](flmadm/README.md).

### Verify the Installation

Then, verify the installation with `flmping` in the pod. Additionally, you can explore more meaningful examples [here](examples):
After starting Flame (via either option), verify the installation with `flmping`:
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For users who choose Option 2 (Local Installation), the binaries are installed to /usr/local/flame/bin by default. These will not be in the system PATH automatically. It is recommended to mention that users should source the environment script or update their PATH before running the verification commands to avoid "command not found" errors.

Suggested change
After starting Flame (via either option), verify the installation with `flmping`:
After starting Flame (via either option), verify the installation with `flmping`. For local installations, you may first need to source the environment script: `source /usr/local/flame/sbin/flmenv.sh`.

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

After installation, the Flame binaries (like flmping and flmctl) are located in the installation prefix (defaulting to /usr/local/flame/bin). To run them as shown in the examples below, users will need to add this directory to their PATH or source the generated environment script (e.g., source /usr/local/flame/sbin/flmenv.sh). Adding a brief note about this would improve the user experience.


```shell
root@560624b037c9:/# flmping
Session <1> was created in <3 ms>, start to run <10> tasks in the session:

Session Task State Output
flmping-UdjmHs 8 Succeed Completed on <fc5afd603feb> in <0> milliseconds with <0> memory
flmping-UdjmHs 6 Succeed Completed on <fc5afd603feb> in <0> milliseconds with <0> memory
flmping-UdjmHs 10 Succeed Completed on <fc5afd603feb> in <0> milliseconds with <0> memory
flmping-UdjmHs 7 Succeed Completed on <fc5afd603feb> in <0> milliseconds with <0> memory
flmping-UdjmHs 2 Succeed Completed on <fc5afd603feb> in <0> milliseconds with <0> memory
flmping-UdjmHs 1 Succeed Completed on <fc5afd603feb> in <0> milliseconds with <0> memory
flmping-UdjmHs 3 Succeed Completed on <fc5afd603feb> in <0> milliseconds with <0> memory
flmping-UdjmHs 5 Succeed Completed on <fc5afd603feb> in <0> milliseconds with <0> memory
flmping-UdjmHs 9 Succeed Completed on <fc5afd603feb> in <0> milliseconds with <0> memory
flmping-UdjmHs 4 Succeed Completed on <fc5afd603feb> in <0> milliseconds with <0> memory


<10> tasks was completed in <473 ms>.
$ flmping
Session <flmping-Sf4R2o> was created in <1 ms>, start to run <10> tasks in the session:

Session Task State Output
flmping-Sf4R2o 1 Succeed Completed on <396003ae48dd> in <0> milliseconds with <0> memory
flmping-Sf4R2o 2 Succeed Completed on <396003ae48dd> in <0> milliseconds with <0> memory
flmping-Sf4R2o 3 Succeed Completed on <396003ae48dd> in <0> milliseconds with <0> memory
flmping-Sf4R2o 4 Succeed Completed on <396003ae48dd> in <0> milliseconds with <0> memory
flmping-Sf4R2o 5 Succeed Completed on <396003ae48dd> in <0> milliseconds with <0> memory
flmping-Sf4R2o 6 Succeed Completed on <396003ae48dd> in <0> milliseconds with <0> memory
flmping-Sf4R2o 7 Succeed Completed on <396003ae48dd> in <0> milliseconds with <0> memory
flmping-Sf4R2o 8 Succeed Completed on <396003ae48dd> in <0> milliseconds with <0> memory
flmping-Sf4R2o 9 Succeed Completed on <396003ae48dd> in <0> milliseconds with <0> memory
flmping-Sf4R2o 10 Succeed Completed on <396003ae48dd> in <0> milliseconds with <0> memory


<10> tasks was completed in <153 ms>.
```

You can check session status using `flmctl` as follows. It also includes several sub-commands, such as `list`:
You can check session status using `flmctl`. Explore more examples [here](examples):

```shell
root@560624b037c9:/# flmctl list -s
ID State App Slots Pending Running Succeed Failed Created
flmping-UdjmHs Closed flmping 1 0 0 10 0 06:57:53
$ flmctl list -s
ID State App Slots Priority Pending Running Succeed Failed Created
flmping-Sf4R2o Closed flmping 1 0 0 0 10 0 13:33:30
```

## CLI Tools
Expand All @@ -115,20 +140,20 @@ Flame provides two separate command-line tools:

### Installing Flame with flmadm

For bare-metal or VM installations, use `flmadm` to install Flame:
For multi-node bare-metal or VM deployments, use `flmadm` to install Flame components on each node:

```shell
# Basic installation (from GitHub)
sudo flmadm install
# On control plane node
sudo flmadm install --control-plane --enable

# Install from local source
sudo flmadm install --src-dir /path/to/flame
# On worker nodes
sudo flmadm install --worker --enable

# Install and start services
sudo flmadm install --enable
# On cache nodes (optional, can be co-located with workers)
sudo flmadm install --cache --enable

# User-local installation (no systemd)
flmadm install --no-systemd --prefix ~/flame
# Or deploy all components on a single node
sudo flmadm install --all --enable
```

For more details, see the [flmadm README](flmadm/README.md).
Expand Down
Loading