> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# iagctl runner

Start a gateway runner.

The `iagctl runner` command starts a gateway runner instance that listens for service execution requests from a gateway server in the same cluster. The runner executes the request and returns the result to the core gateway server. Runners enable distributed gateway deployments by offloading automation execution to dedicated nodes.

## Syntax

```bash
iagctl runner [flags]
```

## Usage notes

### Gateway clusters

You can link multiple gateway servers together if they share the following properties:

* A shared database — either an etcd database or an Amazon DynamoDB table. Set the `GATEWAY_STORE_BACKEND` configuration variable to `etcd` or `dynamodb`.
* The same `GATEWAY_APPLICATION_CLUSTER_ID` value. All resources saved to a gateway database are linked to the cluster ID that was set at the time of creation. When multiple gateway instances read from the same shared database with the same cluster ID, they all have access to the same resources.

For more information, see [Choose a deployment architecture](../choose-deployment-architecture).

### Core servers and runners

By default, a gateway server handles all requests including creating, deleting, and viewing resources as well as executing automations.

When you set the `GATEWAY_SERVER_DISTRIBUTED_EXECUTION` configuration variable to `true`, the core server continues to accept all requests but sends automation execution to runner nodes in the same cluster. The core server accepts requests and delegates execution to the runners.

You can scale out to as many runner nodes as needed. When a core server receives a service execution request, it round-robins across all runner nodes connected to the same etcd server with the same `GATEWAY_APPLICATION_CLUSTER_ID`. The runner returns the execution result to the core server, which passes it back to the requesting client.

To verify that your runner is correctly configured to receive requests, review the `GATEWAY_RUNNER_*` configuration variables in the gateway reference documentation.

## Examples

### Start a gateway runner

```bash
iagctl runner
```

## Options

```bash
  -h, --help   Help for runner
```

## Options inherited from parent commands

```bash
  --profile string   Specify the client profile to use (case-insensitive, defaults to [client] section)
  --config string   Path to the configuration file
  --raw             Display the result of the command in raw format
  --verbose         Enable verbose output
```