Codex Factory: Creating Local Codex Clusters for Developers

In a recent demonstration, the Codex team provided an overview of Codex Factory, a new CLI tool developed in-house and designed to streamline the setup of local Codex clusters for development and testing purposes.

Built by Adam Uhlíř from the Codex team, Codex Factory allows developers to spin up a functional network of Codex nodes using Docker, completely isolated from the testnet and the wider internet.

This tool is especially valuable for developers building applications on top of Codex or contributing to the Codex ecosystem. It provides a predictable, repeatable environment with no dependency on the state or uptime of the public testnet.

Check out the video walkthrough of Codex Factory below and read on for more on how it works.

What Codex Factory Does

Codex Factory spins up a complete mini-network of Codex nodes on your local machine. It uses Docker containers to launch a local blockchain, a bootnode (which also acts as a client), and several host nodes. 

All of this is done with a single command, requiring you to have Node.js and Docker installed.

When the tool is run using the npx codex-factory start command, it does the following:

• Creates a local Docker network.
• Launches a local blockchain (using Hardhat), complete with pre-funded accounts and testnet tokens.
• Starts a bootnode that acts as the coordination point.
• Spawns several host nodes (four by default) that connect to the bootnode and simulate real-world Codex hosts.

The result is a self-contained, functioning Codex environment, running entirely on localhost, which can be used for development or automated testing.

Configuration, Persistence, and Detached Mode

The number of nodes can be configured. The default is one bootnode/client and four host nodes, and this can be scaled down if needed. 

Each node exposes its API on a dedicated port, beginning with the default for the client and incremented for each additional host. Port remapping is not currently supported, but this feature could be added via community pull requests.

Codex Factory does not automatically configure the host nodes with availabilities, meaning that while the nodes are running and capable of providing storage, they are not yet participating in the storage marketplace. 

This gives developers full control over their environment, which is useful for testing specific flows or triggering custom API calls to simulate marketplace behaviour.

Availability setup, storage requests, and data seeding are planned for future subcommands, which will make it even easier to prepare a testbed for realistic workflows.

Codex Factory can also be run in detached mode, allowing the cluster to start in the background and free up the terminal session. This is particularly useful for CI pipelines or when working on multiple terminal tabs.

The containers are persistent by default. If you stop the cluster using the stop command, it retains its state, and when you restart it, it picks up where it left off.

If you need a clean state, using the --fresh argument with the codex-factory start command will delete the state and recreate everything from scratch. The state can also be deleted when stopping the cluster by using codex-factory stop --rm when stopping the cluster.

Codex Factory can also be run with a specific version of Codex. As long as a Docker image exists for that commit, Codex Factory can pull and run it. 

You can also configure the tool to always download and use the newest build of Codex.

Codex Factory already offers a solid framework for developers and testers, and it is designed with extensibility in mind. 

Future iterations could include tools for seeding data, configuring availabilities programmatically, and handling custom port mapping. 

The architecture is simple and developer-friendly, making it easy to contribute or extend based on project needs. We encourage developers to check out the tool’s GitHub repository and contribute to the project.

If you’re interested in joining the Codex network and running a node in Altruistic Mode on the Non-Incentivised Testnet, head over to docs.codex.storage to get started.

To stay up to date with the latest news, follow us on social media or join the Codex Discord.