> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://docs.ampdb.io/api/mcp` to find what you need. # ampd `ampd` is the Amp daemon: the program that runs Amp itself. It's a single binary that contains every one of Amp's services, and its command decides which of them a process runs. You only need it when you run Amp yourself; to use a hosted Amp, you connect to it with a [CLI](/clis/ampctl) or an [SDK](/sdks/typescript) instead. ## Services Amp is made of three services. They coordinate through the [metadata database](/running-amp/metadata-database), a PostgreSQL database that holds Amp's state, and read and write the same [storage](/running-amp/storage), where datasets' Parquet files live. * **[Controller](/running-amp/controller)**: serves the [Admin API](/managing-amp/admin-api), which you use to register and deploy datasets, and schedules the [jobs](/managing-amp/jobs) that build them. * **[Query server](/running-amp/query-server)**: answers SQL queries over [Arrow Flight](/querying/arrow-flight), as one-off batch queries or continuous streams. * **[Worker](/running-amp/worker)**: runs jobs. It extracts data from [providers](/providers), transforms it, and writes it to storage. ## Commands | Command | What it runs | Use it for | | --------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------- | | `ampd solo` | The three services in one process, plus a PostgreSQL server if needed | Development, testing, and CI: [Solo Mode](/running-amp/solo-mode) | | `ampd controller` | The controller | [Distributed Mode](/running-amp/distributed-mode) | | `ampd server` | The query server | [Distributed Mode](/running-amp/distributed-mode) | | `ampd worker --node-id ` | One worker, with the ID you give it | [Distributed Mode](/running-amp/distributed-mode) | | `ampd migrate` | Applies pending migrations to the metadata database, then exits | [Upgrading](/running-amp/upgrading) and first setup | `ampd dev` is another name for `ampd solo`. To choose between solo and distributed mode, see [Choose How to Run Amp](/get-started/choose-how-to-run-amp). ## Options `ampd` has one option of its own. The others belong to a command: `ampd solo` takes [`--amp-dir`, `--flight-server`, and `--admin-server`](/running-amp/solo-mode#options), and `ampd worker` takes [`--node-id`](/running-amp/worker#node-ids). | Option | Environment variable | Description | | ------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `--config ` | `AMP_CONFIG` | The [configuration file](/running-amp/configuration). Required by every command except `solo`, like `--config config.toml`. | | `-h`, `--help` | | Prints help. `ampd solo --help` prints a command's help. | | `-V`, `--version` | | Prints the version, like `ampd v0.0.42`. | `--config` goes before the command. After it, `ampd` doesn't recognize it: :::terminal ```bash ampd server --config config.toml ``` ``` error: unexpected argument '--config' found Usage: ampd server ``` ::: Write `ampd --config config.toml server` instead, or set `AMP_CONFIG` once: ```bash export AMP_CONFIG=config.toml ampd server ``` ## Ports Each service listens on its own port, on every network interface (`0.0.0.0`) by default. Change an address with the setting in the last column. | Port | Service | What it serves | Setting | | ------ | ------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | `1602` | Query server | Arrow Flight (gRPC), and `/healthz` over HTTP on the same port | [`server.flight_addr`](/running-amp/configuration-reference#serverflight_addr) | | `1610` | Controller | The Admin API and `/healthz`, over HTTP | [`controller.admin_api_addr`](/running-amp/configuration-reference#controlleradmin_api_addr) | | `1620` | Worker | `/healthz`, over HTTP | [`worker.health_addr`](/running-amp/configuration-reference#workerhealth_addr) | Solo mode opens all three. ## Health checks Each service answers `GET /healthz` on its port, for load balancers and orchestrators like Kubernetes: :::terminal ```bash curl -i http://localhost:1610/healthz ``` ``` HTTP/1.1 200 OK content-length: 0 date: Fri, 30 Oct 2026 16:51:28 GMT ``` ::: The controller and the query server return `200 OK` once they're listening. The worker returns `200 OK` once it has started its jobs and while it receives job notifications from the metadata database, and `503 Service Unavailable` otherwise. ## Environment variables | Variable | Description | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `AMP_CONFIG` | The configuration file, like `--config`. | | `AMP_CONFIG_*` | Overrides a configuration setting, like `AMP_CONFIG_METADB__URL`. See [Configuration](/running-amp/configuration#environment-variables). | | `AMP_DIR` | Solo mode's [state directory](/running-amp/solo-mode#the-amp-directory), like `--amp-dir`. | | `AMP_FLIGHT_SERVER`, `AMP_ADMIN_SERVER` | Solo mode's [`--flight-server` and `--admin-server`](/running-amp/solo-mode#options). | | `AMP_NODE_ID` | A worker's ID, like `--node-id`. | | `AMP_LOG`, `RUST_LOG`, `AMP_LOG_SPAN_EVENT` | How much `ampd` logs. See [Telemetry](/running-amp/telemetry#logs). | | `OTEL_*` | Where `ampd` exports traces and metrics. See [Telemetry](/running-amp/telemetry#traces-and-metrics). | | `AWS_*`, `GOOGLE_*`, `AZURE_*` | Credentials for object storage. See [Storage](/running-amp/storage#object-storage). | ## Errors and exit codes When `ampd` can't start, or a service stops on an error, it prints the error and its causes on one line, then exits with status `1`, or `2` for a wrong command or option: ``` Exiting with error: Invalid worker node ID | Caused by: Invalid worker ID '1worker': must start with a letter, got '1' ``` Read it from left to right: what failed, then each cause, separated by `->`, down to the root one. The pages of each service and of the [metadata database](/running-amp/metadata-database#troubleshooting) list the common errors. ## Stopping `ampd` stops gracefully on `SIGINT` (Ctrl+C) or `SIGTERM`: each service finishes its shutdown, then the process exits with status `0`. In solo mode, it then stops the PostgreSQL server it manages; send a second signal to exit without waiting for it.