GenieACS: a TR-069 auto configuration server in TypeScript

What an ACS does for a device fleet

GenieACS is a high performance Auto Configuration Server for the remote management of TR-069 enabled devices, which are the customer premises equipment that ISPs ship to homes: routers, modems and gateways that speak the CWMP protocol.

The job of an ACS is to be the other end of that conversation. The device points at an ACS URL, and from then on the ACS can read the device's parameters, set configuration values, trigger a firmware download and collect results. For an operator with tens of thousands of those devices, that conversation is the whole remote management story, and doing it by hand is not possible.

The project describes itself as high performance and lightweight, and states that it uses a declarative and fault tolerant configuration engine for automating complex provisioning scenarios at scale, and that it is battle-tested to handle hundreds of thousands and potentially millions of concurrent devices. That last claim is the project's own, not an independent measurement, but it does explain the shape of the design.

The audience is therefore a network operator or a broadband provider, not a hobbyist. The consumers of the ACS are the devices, and the human-facing surface is the web interface and the REST API.

The language is TypeScript, running on Node.js, with MongoDB as the datastore, and the licence is AGPL-3.0.

Four services, four ports, four jobs

GenieACS is not a single process. The package installs four executables, and each one has a distinct port and a distinct job.

  "bin": {
    "genieacs-cwmp": "bin/genieacs-cwmp",
    "genieacs-fs": "bin/genieacs-fs",
    "genieacs-nbi": "bin/genieacs-nbi",
    "genieacs-ui": "bin/genieacs-ui"
  },

genieacs-cwmp is the service the CPEs talk to. It listens on port 7547 by default, and this is where you point the ACS URL configured in the devices. It is the only mandatory service for a working deployment.

genieacs-nbi is the northbound interface module. It exposes a REST API on port 7557, and the documentation is explicit that it is only required if you have an external system integrating with GenieACS through that API.

genieacs-fs is the file server from which the CPEs download firmware images and such, on port 7567 by default. It exists so that firmware downloads are served over the same infrastructure rather than from a third party host that the devices may not reach.

genieacs-ui serves the web based user interface on port 3000, and it has one argument that is not optional: you must pass --ui-jwt-secret to supply the secret key used for signing browser cookies.

genieacs-ui --ui-jwt-secret secret

Four processes means four things to supervise, four ports to expose or keep private, and a decision about which ones your devices need to reach. That is the operational cost of the design, and it is worth understanding before you install it rather than after.

Master is the v1.3 line, v1.2 is the one to deploy

The first thing the project documentation tells you is which branch to use, and it is the opposite of what you would guess from the name of the repository.

This is the development branch for GenieACS v1.3. It is unstable and not ready for production use. For the latest stable release, see the v1.2 branch. The package manifest agrees: the version recorded there is 1.3.0-dev.

The release history confirms the split. The recent tags are v1.2.16 on 2026-03-29, v1.2.15 on 2026-03-27 and v1.2.14 on 2026-03-13, all on the 1.2 line, and the last push to the repository was on 2026-09-14. So the stable line has had patch releases through the spring, while the development branch has been receiving work since without producing a 1.3 release.

That is a deliberate staging arrangement rather than neglect. The v1.3 line is where the next major release is being prepared, and the 1.2 line continues to receive fixes for operators who cannot move yet.

For an evaluation, that means two different questions. If you want to see what the current stable product does, install from the v1.2 branch or from npm, where the published package is the stable one. If you want to know where the project is going, read the 1.3 branch, the CHANGELOG and ARCHITECTURE.md, and be explicit with your team that you are reading unreleased code.

The documentation site, docs.genieacs.com, is where the complete installation guide for production deployments lives, and that guide is written for the stable release rather than for the development branch.

The dependency list explains the architecture

The package dependencies are short and each one points at a subsystem.

The JavaScript engine is espresso-iisojs, which is the runtime the configuration engine evaluates on. Parsing of JavaScript inside configurations comes from acorn with acorn-globals and acorn-walk, which is what lets the declarative engine read and transform scripts the way the engine will later run them. seedrandom is there to give the engine a reproducible random source, which matters when you want a configuration to behave the same on every evaluation.

The HTTP layer is Koa, with @koa/router for the route table, @koa/bodyparser for request bodies, koa-compress for response compression, koa-send for file serving, and koa-jwt with jsonwebtoken for token handling, which is what the UI's cookie signing and the northbound API authentication are built on. The scheduling of recurring work, such as a device polling schedule, comes from @breejs/later.

Storage is MongoDB through the mongodb driver, with bson for the document types, and ipaddr.js for address handling, which appears in the CPE matching and in the network related configuration objects. iconv-lite handles character set conversion, which is a real requirement when talking to devices that report parameter values in non UTF-8 encodings.

The dev dependencies tell the other half of the story. CodeMirror packages for the configuration editor in the web interface, Tailwind for the styling, ESLint for the linting, and @typescript/native-preview at beta, which is the native TypeScript compiler preview used for the build.

Installing from npm and the first run wizard

The quick start is short because the dependencies are conventional. Install Node.js and MongoDB, with the supported versions being Node.js 12.3 or newer and MongoDB 3.6 or newer.

From npm:

sudo npm install -g genieacs

From source, you clone the repository or download the source archive, change into the source directory and run:

npm install
npm run build

The build produces the services, which you find under the dist/bin directory when building from source.

The first thing you do after starting the UI is open it in a browser. The documentation says that when you open the GenieACS UI in a browser you will be greeted with a database initialization wizard to help you populate some initial configuration. That is the intended onboarding path: the wizard writes the first configuration objects into MongoDB.

Two practical notes from the same section. The UI needs its --ui-jwt-secret argument, and because the cookie signing secret is what protects browser sessions, generating a random one rather than reusing the example value is the obvious move for anything that is not a throwaway test. And for testing without hardware, the project points at genieacs-sim as a dummy TR-069 simulator, which is the fastest way to exercise the CWMP path before a device in the field is pointed at your server.

The ACS URL is the handoff point. Whatever else you configure, the devices have to be told to talk to your instance, and the CWMP service is the one that listens for them on port 7547.

Pointing devices at your own ACS

There is a real alternative to running this software, and it is the arrangement most CPEs ship with: the ACS URL configured in the device points at the vendor's own server, or at one provided by the equipment supplier.

The difference in approach is not subtle. A vendor-hosted ACS is a closed system that knows one model of device and exposes whatever interface its owner chooses. GenieACS is a generic server that speaks CWMP to whatever devices point at it, and its configuration is yours to write.

What you gain is a single provisioning model across a mixed fleet. Instead of one integration per vendor's server, you write one declarative configuration and it applies to every device that matches. That is the entire point of the declarative engine, and it is what turns remote management from a per-vendor integration project into a data problem.

What you take on is responsibility for the parts the vendor would have handled. You run the CWMP endpoint that devices call, you host the firmware images on the file server, you keep MongoDB, and you own the TLS termination and the authentication of the northbound API. The documentation's note that a production deployment needs the complete installation guide, and the existence of both a community forum and a commercial support option, both point at the same conclusion: this is software you operate.

The documentation is published at docs.genieacs.com, with the forum at forum.genieacs.com for community guidance and a support page on genieacs.com for commercial arrangements.

AGPL-3.0, scale claims and the support routes

The licence is AGPL-3.0, with the copyright held by GenieACS Inc. covering 2013 to 2026, and the licence file in the repository.

For an operator running the software internally to manage your own devices, AGPL is workable. For a company that wants to expose a GenieACS based service to its own customers, or to embed parts of it in a product, the network copyleft obligations reach further than MIT or Apache would, and that is a question for your counsel rather than something this page should answer.

On scale, the honest position is that the project claims it is battle-tested to handle hundreds of thousands and potentially millions of concurrent devices, and publishes no independent numbers. The claim is plausible given the architecture, a Node.js service with a MongoDB store and a scheduling library, but nobody has published a benchmark, so treat it as a design intention rather than a measurement.

The support picture is tiered and worth understanding before you need it. The community forum is the documented place to get guidance and help from the community, commercial support options are listed on the company's site, and the repository carries an AGENTS.md file alongside ARCHITECTURE.md and a CHANGELOG.md, so the internals are documented for people who want to read them.

One more practical note for anyone running this in production: the file server is the component that quietly becomes load bearing, because firmware images are large and the devices fetch them repeatedly, and the documentation gives it its own service and its own port rather than folding it into the CWMP process. That separation is deliberate, and it is the part of the deployment to size first.

Editorial conclusion

GenieACS suits an ISP or operator with a fleet of TR-069 CPEs that needs one provisioning configuration applied across every model, and who wants to write that configuration as data rather than as per device scripts. It is the wrong choice for a handful of devices, since the machinery is sized for fleets, and it is the wrong choice if you are unwilling to run MongoDB and follow the project through its 1.x line, because the v1.3 branch is explicitly unstable. Verify three things before you put it in front of real hardware: that the devices can actually reach the CWMP port, that the declarative configuration you write matches the vendor data model of your CPEs, and that the REST API you integrate against exists in the version you deploy rather than only in the development branch.

Frequently asked questions

Official sources

1. genieacs/genieacs on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases