> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ooneex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a microservice

> Scaffold a standalone microservice module with its own entrypoint, env, and Docker setup, fully wired into your project's networking.

A microservice is a self-contained module that runs as its own process. Unlike a regular feature module — which is registered into `AppModule` or `SharedModule` and served by the API — a microservice has its own entrypoint, its own start hook, its own `Dockerfile`, and its own port. The generator creates all of that and wires the service into your project's config so it is reachable from day one.

The `microservice:create` command does the heavy lifting: it scaffolds the module folder, picks a free port, and updates the app config, env config, tsconfig aliases, and commitlint config so nothing is left dangling.

## What it does

* **Scaffolds a standalone module** under `modules/<kebab-name>/` with everything it needs to boot on its own.
* **Picks a free port.** Port `3000` is the API; microservices start at `3001` and the generator takes the next free port.
* **Wires the networking.** The service is declared in the app module config and the root env so other parts of the system can resolve its URL.
* **Stays out of the registry.** A microservice is never registered into `AppModule` or `SharedModule` — it runs standalone.

## Command

```bash theme={null}
ooneex microservice:create [options]
```

## Examples

```bash theme={null}
# Interactive: prompts for the microservice name
ooneex microservice:create

# Provide the name as a flag
ooneex microservice:create --name=billing

# Run against a specific project directory
ooneex microservice:create --name=billing --cwd=/path/to/project
```

## Options

| Option     | Description                                                                                                                  | Default                   |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `--name`   | Microservice name. Normalized to PascalCase with any trailing `Module` stripped; the module folder uses its kebab-case form. | Prompted if omitted       |
| `--cwd`    | Project directory the microservice is created in.                                                                            | Current working directory |
| `--silent` | Suppress prompts and success output.                                                                                         | `false`                   |

See [microservice:create](/cli/commands/microservice-create) for the full command reference.

## What gets generated

Running the command against a name like `billing` creates a complete module under `modules/billing/`:

| File                          | Purpose                                                            |
| ----------------------------- | ------------------------------------------------------------------ |
| `src/index.ts`                | The microservice entrypoint — its own boot, distinct from the API. |
| `src/OnAppStart.ts`           | Start hook that runs when the service comes up.                    |
| `src/BillingModule.ts`        | The module class (`<PascalName>Module`).                           |
| `Dockerfile`                  | Container build for running the service standalone.                |
| `.env.yml`                    | Service-local env, bound to the free port the generator picked.    |
| `roles.yml`                   | Role definitions for the service.                                  |
| `package.json`                | Module package, named `@module/<kebab>`.                           |
| `tsconfig.json`               | TypeScript config for the module.                                  |
| `billing.yml`                 | Module manifest with `type: "microservice"`.                       |
| `tests/BillingModule.spec.ts` | A mirrored test for the module class.                              |

For a full walkthrough of the layout and what each file is responsible for, see [Structure](/microservice/structure).

## Networking it wires

Because a microservice runs as its own process, the rest of the system needs to know how to reach it. The generator wires that up automatically, updating these files when they exist:

| Target                | What changes                                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------------------- |
| `modules/app/app.yml` | Adds the service to the `microservices:` list, with its URL read from the `MICROSERVICE_<SNAKE>_URL` env var. |
| Root `.env.yml`       | Adds the service to the `microservices:` map.                                                                 |
| Root `tsconfig.json`  | Adds the path aliases for the new module.                                                                     |
| Commitlint config     | Registers the new module as a valid commit scope.                                                             |

The URL is resolved through an env var (e.g. `MICROSERVICE_BILLING_URL`), so each environment can point at a different host without code changes. See [Networking](/microservice/networking) for how services discover and call one another.

## Next: compose the service

The scaffold gives you a running, reachable shell. The next step is to fill it with artifacts — controllers, services, repositories, and the rest — so the microservice actually does its work. Generators like the controller and service commands target the new module by name, the same way they target any other module.

See [Composition](/microservice/composition) for building out the service with artifacts.

## Start and stop the microservice

A microservice runs as its own process. Start it from the project root with `app:start`; the `--microservice` flag narrows the run to microservice modules:

```bash theme={null}
# Start every microservice
ooneex app:start --microservice

# Start just one by name
ooneex app:start --microservice=billing

# Start several named services at once
ooneex app:start --microservice=billing,payments

# Run the microservice alongside the api it serves
ooneex app:start --api --microservice
```

`app:start` brings up the shared Docker stack first, then serves each selected microservice's entrypoint with hot reload. To stop the running services, interrupt the process with <kbd>Ctrl</kbd>+<kbd>C</kbd>.

`app:stop` brings down the `app` module's shared Docker stack. A microservice is stopped through the same command only when it ships its own `docker-compose.yml`, in which case the flag narrows the stop to it:

```bash theme={null}
ooneex app:stop --microservice=billing   # bring down a microservice's own Docker stack
```

<Tip>
  Running `ooneex app:start` with no flag starts every `api`, `microservice`,
  and `spa` module together — the simplest way to bring the whole system up.
</Tip>

## Use with Claude and Codex

The generator ships a matching `microservice:create` skill. It runs the scaffold and then guides your AI agent through the follow-up: confirming the networking wiring and composing the service with its first artifacts. Initialize the skills once for your agent:

<Tabs>
  <Tab title="Claude">
    ```bash theme={null}
    ooneex claude:init
    ```

    Then ask Claude in natural language — it maps the request to the generator and runs it:

    ```text Prompt icon="terminal" wrap theme={null}
    Create a billing microservice.
    ```
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    ooneex codex:init
    ```

    Then ask Codex in natural language — it maps the request to the generator and runs it:

    ```text Prompt icon="terminal" wrap theme={null}
    Create a billing microservice.
    ```
  </Tab>
</Tabs>

For example, the prompt above maps to `microservice:create --name=billing`, scaffolds the standalone module on the next free port, and wires it into the app config, env, and tsconfig aliases.

## Related

* [Overview](/microservice/overview) — what microservices are and when to reach for one.
* [Structure](/microservice/structure) — the generated layout, file by file.
* [Networking](/microservice/networking) — how services resolve and call each other.
* [Composition](/microservice/composition) — fill the service with artifacts.
* [Remove](/microservice/remove) — tear a microservice back down.
* [microservice:create](/cli/commands/microservice-create) — the full CLI reference.