FBOSS: Facebook's open source switch control plane

One daemon, and the rest of the stack is still in house

FBOSS is Facebook's software stack for controlling and managing network switches, written in C++. The open source release that exists today consists primarily of one program, the agent daemon, and the project description says as much: applications, libraries and utilities are the shape of the stack, but additional pieces and functionality are still being worked on for release. That makes this tree a part of a much larger internal system rather than a finished distribution, and it changes how a reader should judge it. The single released component is the one Facebook itself runs on every switch it controls, which makes it a rare and honest reference implementation. The agent code lives in fboss/agent. Anyone planning to build a switch on top of FBOSS is planning against a codebase whose centre of gravity is elsewhere, and whose most interesting parts are the ones not published yet.

The agent owns the ASIC and answers ARP and NDP itself

The daemon runs on each switch it manages and controls the hardware forwarding ASIC. It sends forwarding information to that hardware, and it implements control plane protocols such as ARP and NDP in user space, which is the detail that catches people out. The agent is not a passive shim in front of somebody else's network operating system; it is the process that resolves addresses for the box itself. Routes travel on a different path. The agent provides thrift APIs for managing routes, so an external routing control process can get routing information programmed into the hardware forwarding tables. The split is deliberate: the agent owns the ASIC and the link local protocols it has to terminate, while route decisions are made somewhere else and pushed in over thrift. That boundary is the whole architecture, and it explains both what you can build on FBOSS and what you cannot.

The JSON config is a build artifact, not a hand written file

The agent requires a JSON configuration file that specifies its port and VLAN configuration, and sample files sit under fboss/agent/configs. The documentation goes out of its way to tell you not to read them: they are not really intended for human consumption, because at Facebook a piece of internal tooling generates those files. The admission is blunt, and it has a direct consequence for anyone outside the company. The port and VLAN layout of a real switch, expressed in the form this agent wants, normally arrives from a generator that has not been released. You can read the samples to learn the shape of the file and hand edit one for a small topology, but there is no documented general path for producing these files for an arbitrary design. Plan on treating the samples as a schema hint, not as a starting configuration you can scale up. The two directories worth opening first in the tree are the sample configurations and the directory holding the route helper script:

fboss/agent/configs
fboss/agent/tools

The first holds the JSON files the agent accepts; the second holds the small python script used to add and remove routes by hand.

Routes arrive over thrift, because no routing daemon ships

The routing daemon is the missing piece. The agent manages the forwarding tables in the hardware ASIC, but it has to be informed of the current routes through the thrift APIs, and the initial open source release does not contain a routing protocol daemon capable of talking to the agent. The project attributes this to Facebook's own daemon being specific to its environment and unlikely to be as useful to the wider community. The suggested path for general use is to modify existing open source routing tools to speak to the FBOSS agent, and the documentation states plainly that this has not been implemented yet. What ships in its place is a small sample python script in fboss/agent/tools that can manually add and remove routes. For day to day management, most of the internal tools are not ready for release, so the fallback is the thrift compiler, which can generate a python-remote script to allow manual invocation of the agent's various thrift interfaces.

The build instructions live in BUILD.md, not in the README

There is no install command anywhere in the project documentation. Build steps are delegated to a BUILD.md document at the root of the repository, so that file is where a first build begins. The top level layout hints at what a build involves: a CMakeLists.txt, a build/ directory, a cmake/ directory, a buck2 directory, a getdeps.sh script, dependency lists in sdk_dependencies.txt and requirements-dev.txt, plus .clang-format and .pre-commit-config.yaml for formatting and pre-commit checks. A reader starting from nothing should open BUILD.md and follow it rather than guessing a sequence of shell commands, because that document is the only place the real commands are written down. The tree also separates concerns into fboss-sim/, fboss-image/, neteng/, configerator/ and docs/, which tells you that simulation, image building and internal tooling live in their own directories and are not part of the agent daemon itself.

Control from outside the box instead of a daemon on the box

The common shape for a switch is a routing protocol daemon running on the device, speaking to the local networking stack and pushing results into the forwarding table of a vendor network operating system. FBOSS inverts part of that arrangement. Protocol work is pushed outward over thrift to a control process running somewhere else, while the box keeps a daemon that owns the ASIC and the control plane protocols it must terminate itself, ARP and NDP among them. The practical difference is where the operational surface and the failure domain sit. A thrift API is a narrow, scriptable boundary, and the generated python-remote script means a running agent can be poked by hand without a full control plane. The cost is that the switch is not autonomous in the usual sense. With no external process feeding it, it holds no routes beyond what the sample script adds by hand.

A custom licence and no tagged releases to pin

The licensing here is not a standard open source grant. The project uses a custom licence that GitHub cannot classify, and the documentation points only at the LICENSE file, so the actual terms live in that file together with a PATENTS file at the root of the tree. That is a real difference from anything under a well known permissive or copyleft licence, and it has to be read before any use, commercial or otherwise. Releases are the second gap. No GitHub releases have been published for this project, so there is no tagged version to depend on, no published upgrade notes and no changelog to diff against when you pull a newer commit. Development is not frozen, though. The last push was on 2026-10-20, and the project states that FBOSS development is ongoing at Facebook, with plans to keep releasing more components, additional features and improvements to the existing tooling. Activity is real, but it arrives as commits rather than as versions.

Where FBOSS is the wrong tool

FBOSS was designed to handle the needs of Facebook's data center networks, and the documentation says plainly that the initial release will likely require modification and additional development to support other network configurations beyond the features Facebook uses. Until it matures further, it is expected to be of primary interest to network software developers rather than to network administrators hoping to use it as a turnkey solution. Two concrete gaps drive that verdict. There is no routing protocol daemon, so a switch cannot learn routes on its own, and the work of connecting external routing tools to the agent has not been implemented. There is also no released generator for the JSON configuration that the agent requires, so port and VLAN configuration has to be written by hand. The agent targets the forwarding ASIC of Facebook's own switches, and the simulation and image directories in the tree are the parts an outsider is most likely to touch first.

Editorial conclusion

FBOSS belongs to network software developers who want to study or extend a production switch control plane, and to anyone building routing tools that talk to a thrift API. It does not belong to an operations team that needs a working switch image this quarter. Before adopting anything from this tree, check three things: the terms in the LICENSE file, since the licence is a custom one rather than a standard open source grant; the state of the routing path, because no routing protocol daemon is included and the work of connecting external routing tools to the agent has not been implemented; and the build steps in BUILD.md, which are the only place the actual commands are written down. The last push was on 2026-10-20, so the tree is moving, but there is no tagged release to pin.

Frequently asked questions

Official sources

1. facebook/fboss on GitHub
2. Issues
3. README