Skip to main content
A microservice in Talos is a module that runs as its own process. It is built on the same module system as every other module, still exporting a <PascalName>Module of type ModuleType from @talosjs/module with controllers, entities, middlewares, cronJobs, and events. The difference is that instead of being composed into the single app process, it is deployed and started on its own, and the main app/API talks to it over the network. What changes is deployment and networking, not the programming model. Like a regular module, a microservice lives under modules/<kebab-name>/. Unlike a regular module, it is not registered into AppModule/SharedModule. It owns its own entrypoint, start hook, Dockerfile, config, port, and roles, and it is declared as a remote dependency the app reaches by URL.

​
What you get

The programming model carries over unchanged. A microservice exports the same ModuleType shape from @talosjs/module, with controllers, entities, middlewares, cronJobs, and events; if you can write a module, you can write a microservice. What you add is independence. It is its own process with its own Dockerfile and src/index.ts entrypoint, so it ships, scales, and restarts on a schedule separate from the API. It carries a distinct .env.yml on its own port (each microservice takes the next free port starting at 8030) along with its own roles.yml. That separation also draws a network boundary. The app calls the microservice over HTTP, so a fault or slow deploy stays contained behind that boundary instead of taking down the whole app process. Two CLI commands manage the lifecycle, talos microservice:create and talos microservice:remove, with no manual wiring.

​
How it works

A microservice reuses the module system: it exports a <PascalName>Module of type ModuleType, the same as a regular module. What changes is everything around the module. It gets its own entrypoint and start hook, runs as its own containerized process on its own port, and is reached by the app over HTTP rather than being composed into AppModule/SharedModule. The app declares it in modules/app/app.yml under a microservices: list and resolves its address from an environment variable. The table below lines up the two side by side. A microservice is declared in modules/app/app.yml as a named remote whose URL comes from the environment:
The module export itself looks like any other module, with the same ModuleType and the same @talosjs/module import:
The extra files a microservice owns (src/index.ts, src/OnAppStart.ts, Dockerfile, .env.yml, roles.yml) are what turn that module into a self-contained, deployable service.

​
When to reach for one

Reach for a plain module by default: it is composed into the app process and called in-process, which is simpler to build, test, and deploy. Reach for a microservice when a piece of the system needs to deploy, scale, or fail independently of the API, with a separate runtime, its own port, its own container, and its own release cadence. The code inside stays a ModuleType either way, so the choice is about boundaries, not about rewriting your logic.

​
Next steps

  • Structure: the files a microservice owns: entrypoint, start hook, Dockerfile, .env.yml, roles.yml.
  • Composition: exporting the ModuleType (controllers, entities, middlewares, cronJobs, events).
  • Networking: declaring it in app.yml, ports, and wiring the URL through env.
  • Create: scaffold one with talos microservice:create.
  • Remove: tear one down with talos microservice:remove.
  • Module overview: the regular, in-process module it is built on.
  • Deploy a microservice: shipping the API and its microservices.