flameox is a runtime evidence server for coding agents that enables profiling, benchmarking, memory analysis, and execution investigation of Python workloads — all locally without uploading code or data. It provides MCP tools for:
Workspace initialization, validation, and workload configuration via flameox.toml.
Capability management: listing, installing, and approving adapters (e.g., py-spy, Memray, Perfetto).
Capture planning and execution (single-use and detached long-running captures).
Experiment design, execution, and retrieval of trial results.
Artifact import and query for external trace files.
Evidence extraction from various profilers and test frameworks.
Multiple analysis types: CPU hotspots, memory, execution coverage, PyTorch operators, accelerator launches, scaling, and failures.
Stack and trace inspection, including call graphs and trace windows.
Measurement queries across runs.
Investigations, hypotheses, and findings management.
Comparisons, run set freezing, and statistical analysis.
Reduction of failing artifacts.
Workspace integrity validation.
All operations are read-only on evidence except for explicit recording actions, keeping your code and data local.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@flameox Initialize this project and show me which profiling capabilities are available."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Flameox coordinates profilers, benchmark tools, trace processors, and direct local targets. It turns an explicit artifact or command into bounded evidence while keeping durable preservation optional. The agent chooses hypotheses and experiments; Flameox records observed inputs, execution provenance, typed evidence, coverage, and limitations.
There is no workspace to initialize or project configuration to maintain. Pass exact artifact paths to analysis and an explicit argv plus absolute working directory to capture. Flameox does not search parent directories, edit project files, or provide a hosted service.
Configure an MCP client with the global setup command:
npx flameox@latest setupSetup detects supported clients and asks which configurations to update. For automation, select
clients explicitly, for example --client codex --yes or --all --yes; --dry-run reports the
paths and actions without writing. Setup preserves unrelated client configuration and does not
change project files. See the npm package guide for details.
Update existing MCP registrations with:
npx flameox@latest updateupdate --check reports available updates without changing configuration. Updates preserve each
client's provider extras and settings, verify the new environment before changing release pins,
and report which clients need a restart or reconnect. Use --client codex to select one client,
or --version 0.2.8 to select a specific release, including for rollback. The Python CLI exposes
the same flameox update command.
For direct CLI use, pass exact artifact paths or an explicit command:
uvx flameox analyze preview_artifact /absolute/path/to/artifact.json
uvx flameox capture --provider direct --cwd "$PWD" -- python benchmark.pyTo launch the stdio MCP server manually:
uvx flameox mcp serveFor local development, clone the repository, install its development dependencies, and inspect the available tools:
git clone https://github.com/morluto/flameox.git
cd flameox
uv sync --extra dev --extra memory --extra trace --extra cpu
uv run flameox mcp inspectRelated MCP server: io.github.morluto/flameox
Analysis and unpreserved capture use bounded session scratch. Session analysis_id values expire
when evicted or when the server stops. Explicit preservation creates the user-level Flameox data
directory and stores native bytes and a canonical evidence bundle by SHA-256. Set
FLAMEOX_DATA_DIR to choose another location. Preservation is optional; it does not imply full
console-output retention.
Flameox distinguishes observed, derived, and inferred claims. Profiles guide exploration but do not establish causality or performance improvement. Confirmatory claims require representative workloads, declared metrics and estimands, compatible identities, preserved samples, and a semantic oracle.
The MCP server has no workspace binding. It exposes named analysis and capture tools through the
same operation registry as the CLI. Analysis tools accept explicit sources; capture tools accept
a typed target and provider. Tool schemas expose operation-specific fields directly. Inspect the
catalog with flameox mcp inspect; use --tool TOOL_NAME for
focused schemas and examples. The complete contract and current tool catalog are in
the interface guide.
Tools return their full bounded results inline, including failures and recovery actions. Preserved
evidence has a durable evidence_id; inspect_evidence returns its redacted metadata and replay
sources inline.
Capture takes argv, not a shell string. A direct target supplies an absolute working directory and
bounded environment overrides. Results may include next_page; replay its named analysis tool
and arguments unchanged. Capture continuations read collected artifacts and do not rerun the
target. MCP work belongs to the live request, so cancellation applies directly and no detached job
survives a restart.
Architecture describes process and package boundaries.
Storage and evidence defines preservation and provenance.
Investigations covers experiments, comparison, and evidence quality.
Adapters documents provider compatibility and integration policy.
Runtime safety covers limits, recovery, integrity, and privacy.
Interfaces defines CLI and MCP contracts.
Testing describes test selections and known proof gaps.
Flameox requires Python 3.12 or newer and uses the committed uv.lock. See
CONTRIBUTING.md for development setup and contribution guidance.
uv run ruff check src tests tools
uv run ruff format --check src tests tools
uv run mypy src tests tools
uv run pytest -qFlameox is licensed under the MIT License.
Analyze observed runtime launches, graph launches, kernels, and idle gaps.
Inputs: limit (required), run_or_artifact (required), phase, comparison_run_or_artifact. Returns: object
Inspect one bounded execution-evidence collection. When next_cursor is present, repeat the same query with that cursor; use record_analysis to preserve a result.
Inputs: limit (required), run_or_artifact (required), cursor, filters, +2 more. Returns: object
Analyze an explicit filtered failure cohort read-only after list_runs discovery.
Inputs: limit (required), filter. Returns: object
Analyze sampled-profile runs or artifacts for bounded source-linked hotspots; use extract_pyperf/query_measurements for benchmark_samples instead.
Inputs: limit (required), run_or_artifact (required). Returns: object
Analyze memory-profile runs or artifacts for peak, retained-end, and allocation evidence.
Inputs: limit (required), run_or_artifact (required), query. Returns: object
Analyze persisted Nsight Compute rule facts without reopening the native .ncu-rep.
The bounded result includes target qualification, coverage, provider provenance, and a concrete recapture selection when more evidence is needed.
Inputs: limit (required), run_or_artifact (required). Returns: object
Summarize normalized Perfetto evidence from a torch.profiler run or artifact.
This read-only tool never extracts implicitly. If normalized rows are absent, follow
the typed recovery result and call extract_perfetto for the exact run.
Inputs: limit (required), run_or_artifact (required). Returns: object
Summarize an existing experiment without collecting missing trials.
Inputs: experiment_id (required). Returns: object
Request cancellation and cleanup of a server-owned capability setup operation.
Inputs: operation_id (required). Returns: object
Cancel only the exact detached task owned by this server; repeated calls are safe.
Inputs: run_id (required). Returns: object
Request cancellation of one server-owned extraction and return bounded cleanup state.
Inputs: operation_id (required). Returns: object
Compare compatible ordered stages without returning native artifact content.
Inputs: baseline_pipeline_id (required), candidate_pipeline_id (required). Returns: object
Compare exact correctness metrics from two immutable run cohorts.
Inputs: request (required). Returns: object
Preview compatible frozen cohorts without persistence; use record_comparison to save.
Inputs: request (required). Returns: object
Create a bounded generic benchmark scenario, not a provider rollout replay engine.
Inputs: name (required), provider (required), operation (required), server_name (required), +15 more. Returns: object
Create or replace a local inference-server declaration without starting it.
Inputs: mode (required), name (required), model (required), operation (required), +9 more. Returns: object
Write one validated named workload without executing it.
Writes only the project workload configuration, preserves existing workloads and
experiments, and returns the next discovery step. It never executes the command.
Use operation='replace' with the current configuration_id to update an existing workload.
Inputs: argv (required), name (required), operation (required), cwd, +9 more. Returns: object
Create a durable diagnostic question.
Inputs: request (required). Returns: object
Run one current plan with side effects; the token is single-use, then get_run.
Inputs: plan_token (required), expected_plan_id. Returns: object
Execute one bound reducer lifecycle and independently revalidate its candidate.
Inputs: plan_id (required). Returns: object
Extract raw accelerator benchmark samples with explicit timing semantics.
Inputs: run_id (required). Returns: object
Extract bounded findings from an official Compute Sanitizer XML report.
Inputs: run_id (required). Returns: object
Extract bounded execution-path evidence through coverage.py's public API.
Inputs: run_id (required). Returns: object
Extract prompt-free AIPerf requests or vLLM aggregate measurements.
Inputs: run_id (required), provider (required). Returns: object
Extract bounded prompt-free Mooncake request schedule evidence.
Inputs: run_id (required). Returns: object
Extract bounded per-case metrics from registered kernel-validation evidence.
Inputs: run_id (required). Returns: object
Start durable Memray extraction; poll get_extraction with the operation ID.
Inputs: run_id (required), idempotency_key (required), temporary_allocation_threshold. Returns: object
Extract bounded evidence from a Node/V8 CPU profile.
Inputs: run_id (required). Returns: object
Extract bounded evidence from a Node/V8 sampling heap profile.
Inputs: run_id (required). Returns: object
Extract bounded metrics through NVIDIA's installed ncu_report interface.
Inputs: run_id (required). Returns: object
Extract curated evidence from an imported official Nsight Systems SQLite export.
Inputs: run_id (required). Returns: object
Extract NVBench sample times and frequencies from a preserved bundle.
The run must contain exactly one primary NVBench JSON artifact and zero or more sidecar artifacts declared by the JSON document.
Inputs: run_id (required). Returns: object
Extract bounded semantic observations emitted through flameox.sdk.
Inputs: run_id (required). Returns: object
Normalize an explicitly registered OTLP file artifact into evidence tables.
Inputs: run_id (required), artifact_id. Returns: object
Run versioned curated queries through a configured local Trace Processor.
Inputs: run_id (required), artifact_id. Returns: object
Extract public pyperf run, warmup, loop, and value evidence.
Inputs: run_id (required). Returns: object
Extract pytest phase, fixture, worker, outcome, and failure-latency evidence.
Inputs: run_id (required). Returns: object
Extract repeated startup, peak RSS, and package-grouped import evidence.
Inputs: run_id (required). Returns: object
Return repeated span signatures as bounded derived evidence.
Inputs: artifact_id (required), limit, cursor, minimum_repetitions. Returns: object
Freeze a bounded cohort against one corpus snapshot.
Inputs: request (required). Returns: object
Return bounded metadata and an opaque resource URI, never a host path or bytes.
Inputs: artifact_id (required). Returns: object
Read one pipeline and bounded compatible comparison candidates.
Inputs: pipeline_id (required), candidate_limit. Returns: object
Read durable capability setup state after the original request disappears.
Inputs: operation_id (required). Returns: object
Inspect allowed parameters and validation metadata, then call the matching plan tool.
Inputs: kind (required), name (required). Returns: object
Reconnect to bounded progress and lifecycle status for one detached run.
Inputs: run_id (required). Returns: object
Resolve a known typed reference; pass ref_type and its ID separately after discovery.
Inputs: ref_id (required), ref_type (required). Returns: object
Reconstruct one bounded experiment outcome from durable evidence.
Inputs: experiment_id (required). Returns: object
Read durable extraction progress, outcome, and recovery after disconnect.
Inputs: operation_id (required). Returns: object
Read one immutable completed fault experiment result.
Inputs: result_id (required). Returns: object
Return the current finding revision with its exact evidence edges.
Inputs: finding_id (required). Returns: object
Return bounded source-linked direct callees for a frame.
Inputs: limit (required), frame_id (required), run_or_artifact (required), cursor, +1 more. Returns: object
Return bounded source-linked direct callers for a frame.
Inputs: limit (required), frame_id (required), run_or_artifact (required), cursor, +1 more. Returns: object
Return the current hypothesis revision.
Inputs: hypothesis_id (required). Returns: object
Return one current investigation projection.
Inputs: investigation_id (required). Returns: object
Return explicit timestamp, identity, and missing-parent evidence.
Inputs: artifact_id (required), limit. Returns: object
Return, but never execute, the installed native viewer command.
Inputs: artifact_id (required). Returns: object
Return bounded parent/child transitions without interpreting causality.
Inputs: artifact_id (required), limit, cursor, trace_id, +1 more. Returns: object
Return normalized OTLP spans overlapping a bounded time range.
Inputs: end_ns (required), start_ns (required), artifact_id (required), limit, +2 more. Returns: object
Return bounded process observations with explicit visibility coverage.
Inputs: run_id (required), limit, phase, cursor. Returns: object
Reconnect to one immutable terminal reduction result.
Inputs: reduction_id (required). Returns: object
Hydrate a run selected by list_runs; use an analyze_* tool for bounded interpretation.
Inputs: run_id (required). Returns: object
Return bounded representative stacks containing a frame.
Inputs: limit (required), frame_id (required), run_or_artifact (required), cursor, +1 more. Returns: object
Return bounded trace slices overlapping a declared time window.
Inputs: limit (required), end_ns (required), start_ns (required), artifact_id (required), +2 more. Returns: object
Import one project-local artifact and preserve producer identity.
Chrome traces with Torch profiler markers are identified automatically. Use
kind='execution_trace' for Chrome/Torch traces, then run extract_perfetto before
analyze_pytorch. If detection is ambiguous, set producer='torch.profiler'.
Inputs: kind (required), path (required), sensitivity (required), profile, +4 more. Returns: object
Import native compiler evidence and register one lineage per dump group.
Inputs: path (required), sensitivity (required), source_root. Returns: object
Import an NVBench JSON and its provider-declared sidecars as one atomic bundle.
Parses the primary JSON first to discover which sidecar files the
document references. Only those files are imported — no arbitrary
sibling files are accepted. Each sidecar's expected byte length is
bound to ``declared_size * 4`` (float32) and verified after import.
Inputs: path (required), sensitivity (required), source_root, expected_sha256. Returns: object
Preserve one native SARIF 2.1.0 report and project bounded static candidates.
The native report remains an immutable analysis-result artifact. Static candidates are source-scoped analyzer output, not Findings or confirmation of runtime behavior.
Inputs: path (required), sensitivity, source_root, exclude_paths, +1 more. Returns: object
Preserve a native Metal trace bundle and bounded xctrace TOC export.
Inputs: path (required), source_root, max_export_bytes. Returns: object
Initialize Flameox in the fixed project root after it has been verified.
Inputs: no named parameters. Returns: object
Discover bounded immutable pipelines by run, name, producer, or artifact.
Inputs: limit, cursor, run_id, producer, +2 more. Returns: object
Page every reduction that produced an artifact selected by get_artifact.
Inputs: limit (required), artifact_id (required), cursor. Returns: object
List bounded artifact metadata from one pinned corpus snapshot.
Inputs: limit (required), cursor. Returns: object
List capabilities and setup actions scoped to a selected capture adapter.
Omit adapter for a complete read-only inventory. In that mode, the per-capability setup
fields and available_setup_adapters are informational only; select an adapter and call
this tool again before mutating the managed environment. Managed setup never executes a
workload.
Inputs: mode, adapter. Returns: object
Discover declared workflows before planning; this never runs them.
With no arguments, list workloads. Pass kind='experiment' or
kind='fault_experiment' to list declared experiments.
Inputs: kind, limit, cursor. Returns: object
Return one bounded page of immutable trials for an experiment.
Inputs: limit (required), experiment_id (required), cursor. Returns: object
List bounded current finding projections.
Inputs: limit (required), cursor. Returns: object
List declared inference servers and scenarios without probing or execution.
Inputs: no named parameters. Returns: object
Page through prompt-free requests with one typed outcome and no derived status fields.
Inputs: run_id (required), limit, cursor. Returns: object
List bounded current investigation projections.
Inputs: limit (required), cursor. Returns: object
Discover a filtered run cohort; follow next_cursor without changing filters.
Inputs: limit (required), cursor, filter. Returns: object
Bind one current capture without running it.
The default auto mode runs the declared workload directly in the local environment and
records that no enforced descendant containment was used. Use managed only when the
project policy explicitly requires containment, and use trusted_local to request the
same direct local execution explicitly. This tool never runs a measurement, but an
adapter may execute a bounded compatibility probe such as NVBench ``--version``.
Inputs: adapter (required), parameters (required), workload_name (required), capture_mode, +6 more. Returns: object
After workflow and capability discovery, bind a declared experiment; then run it.
Inputs: adapter (required), parameters (required), experiment_name (required), investigation_id (required), +1 more. Returns: object
Bind a declared loopback Toxiproxy experiment and its exact toxic scenarios.
Toxiproxy must already be prepared by start_capability_setup; planning neither
downloads nor starts it.
Inputs: parameters (required), experiment_name (required), investigation_id (required), hypothesis_id. Returns: object
Build a diagnostic-only profile plan for one managed vLLM server.
Inputs: profiler (required), server_name (required), scenario_name (required), measurement_run_id (required), +1 more. Returns: object
Qualify one benchmark launcher and construct a typed execution plan.
Inputs: scenario_name (required), timeout_seconds. Returns: object
Bind immutable input and approved reducer/predicate identities before execution.
Inputs: request (required). Returns: object
Approve one installed third-party adapter by exact installed package identity.
This records agent-created provenance under the workspace lock; it does not install a
package, import plugin code, or execute a workload. Call list_capabilities again.
Inputs: adapter (required), distribution (required). Returns: object
Inspect declared workload Python distributions in its bound interpreter.
This operation never installs packages, mutates an environment, or executes the workload; in other words, it never executes user code. The result includes an active preflight and tells the agent whether to plan capture or fix the declared environment outside Flameox.
Inputs: workload_name (required). Returns: object
Read bounded UTF-8 process or validation output without exposing a host path.
Inputs: offset (required), max_bytes (required), max_lines (required), artifact_id (required). Returns: object
Validate preserved native bytes and create a semantically qualified import run.
Inputs: profile (required), artifact_id (required), source_run_id (required). Returns: object
Query normalized measurements through reviewed filters and cursors.
Inputs: limit, cursor, run_id, artifact_id, +2 more. Returns: object
Return one cursor-bounded page of source-scoped static candidates.
Inputs: limit (required), run_id (required), cursor. Returns: object
Return one cursor-bounded page of provider-reported Triton autotune selections.
Inputs: limit (required), run_id (required), cursor. Returns: object
Rebuild only the disposable catalog from immutable corpus evidence.
Inputs: no named parameters. Returns: object
Persist a curated analysis; use analyze_* first for read-only preview.
Inputs: request (required). Returns: object
Persist a reviewed comparison; use compare_run_sets for read-only preview.
Inputs: request (required). Returns: object
Record or revise an evidence-linked finding.
Inputs: request (required). Returns: object
Record or revise a falsifiable hypothesis.
Inputs: request (required). Returns: object
Persist a correctness comparison and exact input provenance.
Inputs: request (required). Returns: object
Bind a bounded ordered pipeline to existing immutable run artifacts.
Inputs: request (required). Returns: object
Attach validated immutable correctness evidence to its exact producing run.
Inputs: path (required), run_id (required), sensitivity (required), expected_run_revision (required), +2 more. Returns: object
Execute all current trials from one single-use plan, then inspect get_experiment.
Inputs: plan_token (required). Returns: object
Run every baseline and declared treatment through its managed loopback proxy.
Inputs: plan_token (required). Returns: object
Run one diagnostic-only profile window against a managed vLLM server.
Inputs: plan_token (required), expected_plan_id. Returns: object
Execute one qualified generic benchmark against a managed or existing-local server.
Inputs: plan_token (required), expected_plan_id. Returns: object
Start detached capability provisioning and return its durable operation ID.
Use the same idempotency key to reconnect after a lost request. Poll
get_capability_setup for named phases, item outcomes, and the terminal receipt;
cancel_capability_setup requests cleanup of owned work.
Inputs: adapters (required), idempotency_key (required), memray_reader_version. Returns: object
Start one current plan once; reconnect by run_id without keeping this call open.
Inputs: plan_token (required), idempotency_key (required). Returns: object
Render one bounded canonical proof summary and its Markdown view.
Inputs: request (required). Returns: object
Validate manifests and schemas; optionally hash every payload.
Inputs: mode. Returns: object
Inspect flameox.toml without writing or executing anything.
Use this after workspace initialization to decide whether to call configure_workload
or list_declared_workflows. Invalid configuration is reported without replacement.
Inputs: no named parameters. Returns: object
Return workspace status; on first use, follow WORKSPACE_NOT_FOUND recovery.
Inputs: no named parameters. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 111 tools
Most tools name an exact resource and action, making pairs like list_runs/get_run or plan_capture/execute_capture_plan easy to tell apart. However, the sheer number of get_*, list_*, extract_*, and analyze_* tools, plus near-neighbor pairs like compare_run_sets/compare_kernel_validation, introduces real selection risk.
The dominant verb_noun snake_case convention is consistent across plan_*, extract_*, list_*, get_*, and analyze_* tools. Minor deviations such as workspace_status, workload_configuration_status, extract_memray behaving like a start operation, and get_native_viewer_plan keep it from a perfect score.
111 tools is an extreme surface for any MCP server, far beyond a focused, well-scoped toolset. Even if each tool serves a distinct profiling sub-domain, an agent would have to navigate an overwhelming and impractical number of choices.
The toolkit covers an impressively broad lifecycle: workspace setup, workload configuration, planning, execution, extraction, analysis, artifact pipelines, inference, experiments, fault injection, comparisons, hypotheses, and findings. Minor gaps exist around generic resource removal/update operations, but the domain is largely immutable by design and workflows generally have no dead ends.
A paid remote MCP for agent memory MCP, built to return verdicts, receipts, usage logs, and audit-re
Tamper-evident proof creation and verification for AI agents via MCP, A2A, and REST.
A paid remote MCP for AI SDK data query MCP, built to return verdicts, receipts, usage logs, and aud
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
