---
title: Run the API service
description: Build and serve the HermesOS API, check that it is healthy, and scrape its metrics.
url: https://hermesos.thally.app/guides/run-the-api
---

# Run the API service

Build and serve the HermesOS API, check that it is healthy, and scrape its metrics.

By the end of this guide the HermesOS API will be serving locally and reporting
its own health and metrics.

## Before you begin

Build the workspace first — see the [Quickstart](/quickstart). The API resolves
other packages through their built output.

## Build and start

```bash
pnpm --filter @hermes/api build
PORT=3000 node apps/api/dist/main.js
```

`PORT` selects the listening port. Without it the service uses its built-in
default.

## Confirm it is healthy

```bash
curl http://127.0.0.1:3000/livez
```

Two health routes answer different questions, and the difference matters when
you wire an orchestrator:

| Route | Question | Use it for |
| --- | --- | --- |
| `/livez` | Is the process up and not wedged? | Liveness probe — restart on failure |
| `/readyz` | Are dependencies reachable? | Readiness probe — remove from rotation |

Restarting on a failed **readiness** check is the classic mistake: a database
blip becomes a restart loop across every replica at once.

## Identity

```bash
curl http://127.0.0.1:3000/
```

Returns the service identity — useful for confirming which build is deployed
behind a load balancer.

## Metrics

```bash
curl http://127.0.0.1:3000/metrics
```

Prometheus exposition format, ready to scrape. Point a scrape config at this
path:

```yaml
scrape_configs:
  - job_name: hermes-api
    static_configs:
      - targets: ['127.0.0.1:3000']
```

## Run it in Docker

The repository ships a `Dockerfile` and a `docker-compose.yml`:

```bash
docker compose up --build
```

> **Note:**
  `docs/deployment` in the HermesOS repository covers building, running, and
  operating the service in more depth than this page.

## What success looks like

- `/livez` reports the service healthy
- `/readyz` reports dependencies reachable
- `/metrics` returns Prometheus text

## Next steps

#### [API reference](/api)

    Every endpoint, with a live playground.

#### [Troubleshooting](/troubleshooting)

    What to do when something reports unhealthy.