> **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.

# ampctl worker

`ampctl worker` shows the [workers](/managing-amp/workers) registered with Amp: the processes that run its jobs, like
extracting a chain or materializing a derived dataset. A worker sends a heartbeat about every second, so its last
heartbeat tells you whether it's alive, and its build information tells you which version of Amp it runs. To find and
fix a worker that stopped running jobs, see [Troubleshooting Workers](/managing-amp/workers/troubleshooting).

## Prerequisites

* A running Amp, like the one the [Quickstart](/get-started/quickstart) starts with
  [`ampd solo`](/running-amp/solo-mode).
* [`ampctl` installed](/clis/ampctl#install) and [connected to it](/clis/ampctl#connect-to-amp).

Every command also takes `ampctl`'s [global flags](/clis/ampctl#global-flags): `--admin-url`, `--auth-token`, and
`--json`, which prints [JSON](/clis/ampctl#json-output) instead of text.

## `ampctl worker list`

Lists every worker that has registered with Amp, with its last heartbeat.

```
ampctl worker list
```

It takes no arguments. `ampctl worker ls` is the same command.

:::terminal
```bash
ampctl worker list
```

```
Workers:
  worker (last heartbeat: 2026-10-30T17:14:44.911695+00:00)
```
:::

Solo mode runs one worker, named `worker`. A [distributed deployment](/running-amp/distributed-mode) lists each
`ampd worker` by its node ID. A worker that stopped stays in the list with the last heartbeat it sent, so compare that
time with the current time to tell which workers are down. With no workers registered, the command prints
`No workers found`.

With `--json`, each worker has its `node_id` and `heartbeat_at`:

:::terminal
```bash
ampctl worker list --json | jq -r '.workers[] | "\(.node_id) \(.heartbeat_at)"'
```

```
worker 2026-10-30T17:14:44.911695+00:00
```
:::

```json
{ "workers": [{ "node_id": "worker", "heartbeat_at": "2026-10-30T17:14:44.911695+00:00" }] }
```

## `ampctl worker inspect`

Shows a worker's registration times, last heartbeat, and the version of Amp it runs.

```
ampctl worker inspect NODE_ID
```

| Argument  | Type   | Default  | Description                                                                                                                                                            |
| --------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NODE_ID` | string | required | The worker's node ID, as [`ampctl worker list`](/clis/ampctl/worker#ampctl-worker-list) prints it, like `worker`. It starts with a letter, followed by letters, digits, `_`, `-`, or `.`. |

`ampctl worker get` is the same command.

:::terminal
```bash
ampctl worker inspect worker
```

```
Node ID: worker
Created: 2026-10-30T17:04:37.819621+00:00
Registered: 2026-10-30T17:10:46.832488+00:00
Heartbeat: 2026-10-30T17:14:44.911695+00:00

Worker Info:
  Version: v0.0.42
  Commit: f27102fd59608258dc58a6dbbaac880f124364ae
  Commit Timestamp: 2026-09-24T19:45:31.000000000+02:00
  Build Date: 2026-09-24
```
:::

| Field              | JSON field              | Description                                                                                        |
| ------------------ | ----------------------- | -------------------------------------------------------------------------------------------------- |
| `Created`          | `created_at`            | When a worker with this node ID first registered.                                                  |
| `Registered`       | `registered_at`         | When the worker last registered, which it does each time it starts. Here, it restarted at 17:10.   |
| `Heartbeat`        | `heartbeat_at`          | When the worker last sent a heartbeat.                                                             |
| `Version`          | `info.version`          | The version of `ampd` the worker runs: a release tag like `v0.0.42`, or a commit for other builds. |
| `Commit`           | `info.commit_sha`       | The commit `ampd` was built from.                                                                  |
| `Commit Timestamp` | `info.commit_timestamp` | When that commit was made.                                                                         |
| `Build Date`       | `info.build_date`       | When `ampd` was built.                                                                             |

To check that every worker runs the version you expect, read `info.version` from the JSON output:

:::terminal
```bash
ampctl worker inspect worker --json | jq -r '.info.version'
```

```
v0.0.42
```
:::

### Errors

* `✗ worker not found: worker-01`: no worker with that node ID has registered. Check the IDs
  [`ampctl worker list`](/clis/ampctl/worker#ampctl-worker-list) prints.
* `error: invalid value '1worker' for '<NODE_ID>': Invalid worker ID '1worker': must start with a letter, got '1'`:
  the node ID isn't valid, so it can't belong to a worker.