# Move Base Flex is a navigation interface layer, not a navigation stack

> naturerobots/move_base_flex defines abstract planner, controller and recovery plugin interfaces for ROS, exposes them as separate action servers, and leaves the executive and the map representation to the user. The interfaces are the product, which is also why adopting it means writing plugins rather than installing a stack.

**naturerobots/move_base_flex** — Move Base Flex: A Highly Flexible Navigation Framework

- Repository: https://github.com/naturerobots/move_base_flex
- Stars: 548 · Forks: 183
- Language: C++
- License: BSD-3-Clause
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/naturerobots-move-base-flex

## Why an interface layer exists at all

Move Base Flex, abbreviated MBF, is described as a modular and map-agnostic navigation framework for ROS that provides well-defined interfaces and action servers for path planning, control and recovery behaviours. The README is careful about what it is not. Rather than being a complete navigation stack, MBF serves as an adaptable interface layer that lets developers design and integrate their own navigation systems using arbitrary map representations and custom plugin implementations. That distinction decides who should care. If you want a robot to navigate with a 2D costmap today, a full stack gives you working planners and controllers immediately. MBF is for the other case, where the map is a mesh, a voxel grid, or something a 3D occupancy grid, and where the decisions about which planner to run belong to software outside the navigation code. The design goal, in the project's own framing, is that the same interface supports a flat indoor floor plan and an outdoor terrain mesh, and that you can compare implementations scientifically because the interface does not change between them.

## Abstract base classes for planner, controller and recovery

The core mechanism is a set of abstract execution classes. MBF defines abstract base classes for the nav core plugin interfaces BaseLocalPlanner, BaseGlobalPlanner and RecoveryBehavior, and the abstraction is extended to give plugins a rich and expressive interface. The interesting part is what a plugin can return. The abstract interfaces let plugins return valuable information in each execution cycle, for example why a valid plan or a velocity command could not be computed, and that information is then passed to the external executive logic through the feedback and result of the planning, navigation or recovering actions. The execution classes implement the abstract behaviour without binding the software to 2D costmaps. In the project's terms, SimpleNav or MeshNav is just a particular implementation of a navigation system whose execution classes implement the abstract ones and bind the system to costmaps. The same set of interfaces therefore serves flat terrain and irregular terrain, and the framework also provides a SimpleNavigationServer class that has no costmap binding at all, for systems that need no map representation.

## Three action servers and an executive that lives outside

The modularity comes from splitting navigation into separate action servers for path planning, control and recovery, which lets external deliberation software coordinate complex strategies, with behaviour trees, SMACH or custom logic given as examples. The philosophy is that the component that decides what to do is not the same thing as the component that does it, so the deciding part is left to you. On top of that separation, multiple planners, controllers and recovery behaviours can be loaded at the same time, selected at run time, or executed in parallel using different concurrency slots. That last point is the one that changes how you write the executive. A system with three controllers running concurrently needs a rule for which one is authoritative, and the README lists auto selecting the active controller when controllers run concurrently as planned future work, so today that arbitration is your code's job. Feedback is where the framework spends its effort, since all actions expose detailed feedback, results and error codes to give transparent runtime information for debugging and system supervision.

## The package layout separates abstractions from the simple server

The repository root shows a package structure rather than a single library. There is mbf_abstract_core/ and mbf_abstract_nav/ for the abstract interfaces, mbf_simple_core/ and mbf_simple_nav/ for navigation components that need no map representation, mbf_msgs/ for the action and message definitions, and mbf_utility/ for shared helpers. Two more directories matter for anyone integrating MBF with their own stack. mbf_test_utility/ is described as a package that helps with integration tests, and it is listed as only a test dependency, so it does not become part of your shipped node graph. rviz_mbf_plugins/ holds the visualisation plugins, which is how you watch a plan or a recovery cycle from the RViz side rather than from log output. The move_base_flex/ directory sits at the root as the umbrella package, and doc/ carries the architecture diagram and logo assets referenced by the README. Two small files describe the project to tooling: source_dependencies.yaml for the build system to resolve sources, and .clang-format for the C++ style, which tells you the code is C++ even though the interfaces are consumed through ROS messages and action servers.

## Three CI targets and a first ROS 2 release dated 16.10.2024

The badges at the top of the README point to three separate GitHub Actions workflows, named humble, jazzy and lyrical, so the project is built and tested against three ROS 2 distributions in parallel. The announcements section records that the first working ROS 2 version of Move Base Flex was published on 16.10.2024, targeting the humble distro and including most of the components known from the ROS 1 era: mbf_abstract_core and mbf_abstract_nav, mbf_simple_core and mbf_simple_nav for navigation components that need no map representation, mbf_utility, and mbf_msgs, plus mbf_test_utility as a test-only dependency. The default branch is ros2, and the ROS 1 implementation lives on the noetic and master branches, which matters if you are migrating an existing move_base setup. The README does not give a colcon build or workspace setup command, so the practical entry point is the repository itself together with the CI workflow files, which show how the packages are built for each distro. The ROS 1 lineage explains a lot about the design. MBF was originally developed for ROS 1 by Magazino as a backwards-compatible replacement for move_base, offering a more flexible and transparent architecture when no modular alternative was available, and it has been deployed in production, for example to control TORU robots in dynamic warehouse scenarios at Magazino.

## The limitation: you still have to write every behaviour

This is the point at which an honest evaluation has to say the obvious. MBF gives you interfaces, action servers and a messaging contract. It does not give you a global planner that works on your map, a controller that respects your kinematics, or a recovery behaviour set, because those are exactly the parts the framework abstracts away. The cost of the abstraction is paid in implementation effort, and for a project with unusual maps that trade is a good one. For a project with a standard 2D costmap and no unusual executive logic, it is pure overhead. The gap list in the README also shows how much is still open, with an Ackermann steering API, a multi goal API plus action, constraints-based goals, new navigation server and core packages using grid_map, and an auto selection rule for concurrently running controllers all listed as planned work. Until a feature lands, you implement it yourself or you do without it. Another constraint is architectural rather than functional. Because the interfaces are map-agnostic by design, a plugin written against them has to express its world in the abstract terms, which is friction that a stack designed around one map type never has.

## An interface layer versus a complete stack, and the connector in between

The alternative is a full navigation stack, and the README names the comparison point. With the advent of ROS 2 and newer navigation frameworks such as Nav2, MBF continues to serve as a lightweight, interface-oriented foundation for research, prototyping and customised navigation systems. The difference in approach is that a complete stack ships planners, controllers and recovery behaviours wired together with a fixed internal executive, whereas MBF ships the contract between those pieces and expects the executive to be external software such as a behaviour tree. The consequence for a team is concrete. With a stack you tune parameters. With MBF you write the plugins, and you get the freedom to select implementations at run time, run several in parallel through different concurrency slots, and choose the map representation per deployment. The repository points at the practical bridge between the two worlds, the MBF Nav2 Connector, which provides 2D navigation on 2D costmaps by translating actions to nav2, and the MBF Deliberation Examples, which demonstrate invoking MBF actions with behaviour trees and SMACH independently of the chosen map representation. Mesh Navigation is offered as the 3D counterpart, implementing the same interfaces on mesh surfaces. If your project needs 2D costmap navigation, the connector may be all you need.

## Conclusion

Move Base Flex fits research and prototyping work where the map representation is not a 2D costmap, or where an external executive such as a behaviour tree must own the decision of which planner or controller runs. It does not fit a team that wants a working navigation stack out of the box, since every planner, controller and recovery behaviour has to be implemented by you. Before committing, check that the package set you need exists in the ROS 2 branch you target, and note that the last push was on 2026-10-20 with no tagged releases, so track the ros2 branch rather than a version number.

## FAQ

### Is Move Base Flex a full ROS navigation stack?

No. The README says that rather than being a complete navigation stack, MBF serves as an adaptable interface layer that enables developers to design and integrate their own navigation systems using arbitrary map representations and custom plugin implementations. The planner, controller and recovery behaviours are yours to write.

### Which ROS 2 distributions does move_base_flex support?

The README shows three CI workflows, named humble, jazzy and lyrical, and the first ROS 2 version was published on 16.10.2024 targeting the humble distro. The default branch is ros2, with the ROS 1 implementation on the noetic and master branches.

### Can I use move_base_flex with a 2D costmap instead of a mesh?

The interfaces are independent of the map representation, and the MBF Nav2 Connector provides 2D navigation on 2D costmaps by translating actions to nav2. Mesh Navigation is listed as the 3D implementation of the same interfaces.

### Which packages make up the ROS 2 version of Move Base Flex?

The README lists mbf_abstract_core, mbf_abstract_nav, mbf_simple_core, mbf_simple_nav, mbf_utility and mbf_msgs, plus mbf_test_utility as a test-only dependency for integration tests.

## Sources

- [Issues](https://github.com/naturerobots/move_base_flex/issues)
- [License: BSD-3-Clause](https://github.com/naturerobots/move_base_flex/blob/ros2/LICENSE)
- [naturerobots/move_base_flex on GitHub](https://github.com/naturerobots/move_base_flex)
- [README](https://github.com/naturerobots/move_base_flex/blob/ros2/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/naturerobots-move-base-flex