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

# Configure gateway client

> Configure client nodes to interact with gateway servers for resource management and service execution.

Client configuration enables interaction with gateway servers for resource management and service execution. The client configuration section specifically applies to client nodes connecting to gateway servers.

You can connect to your gateway server from a local client on the same machine as your server, or, you can install the gateway client on a separate machine.

## Local client (same machine as server)

For RPM/DEB installations, the client functionality is included with the server installation.

The gateway application mode enables you to configure whether `iagctl` acts as a server, client, or other modes when executed. By default, the application mode is set to `server` to manage connections to Gateway Manager. To send requests to your server, set the application mode to `client`.

#### Set the application mode to client

```bash
export GATEWAY_APPLICATION_MODE=client
```

#### Add iagctl to your system path

```bash
export PATH=/opt/gateway:$PATH
```

#### Log in as admin

1. Run `iagctl` login admin.
2. Enter `admin` when prompted for the initial password.
3. Create a new password when prompted. Your password must be longer than 8 characters.
4. Follow the remaining prompts to finish logging in.

## Install and configure a separate client

#### Install gateway client

Install a gateway client on a separate machine to manage the resources on your gateway server.

Download the Gateway binary executable for your particular operating system from the Itential software repository.

#### Linux installation

1. Navigate to your Downloads folder and extract the archive. Before running the following command, update `x.y.z` and `arch` to reflect the version you downloaded.

```bash
tar -zxvf iagctl-x.y.z_linux_arch.tar.gz
```

2. Run the extracted executable:

```bash
./iagctl
```

3. Copy the file to your bin directory:

```bash
mv ./iagctl /usr/local/bin/iagctl
```

#### Mac installation

1. Navigate to your Downloads folder and extract the archive. Before running the following command, update `x.y.z` and `arch` to reflect the version you downloaded.

```bash
tar -zxvf iagctl-x.y.z_darwin_arch.tar.gz
```

2. Run the extracted executable:

```bash
./iagctl
```

3. When a security warning appears, click **Cancel**.
4. Navigate to your **System Settings** and select **Privacy and Security**.
5. Under **Security**, select **Allow Anyways** where it says "iagctl was blocked from use".
6. Provide your password or fingerprint to confirm.
7. Copy the file to your bin directory:

```bash
mv ./iagctl /usr/local/bin/iagctl
```

#### Configure client

Create a client configuration file at `~/.gateway.d/gateway.conf`.

The configuration sections relevant to client nodes include `[application]`, `[client]`, and `[log]`. See [Configuration variables](./configuration-variables-overview) for more information.

#### Example client configuration

The `host` value should match the server where your Gateway server is running.

```bash
[application]
mode = client
# CA certificate for verifying server certificates in mutual TLS
ca_certificate_file = ~/.gateway.d/certificates/ca.pem

[client]
host = gateway-server-hostname
port = 50051
use_tls = true
# Client certificates for mutual TLS authentication
certificate_file = ~/.gateway.d/certificates/client.pem
private_key_file = ~/.gateway.d/certificates/client-key.pem
```

## Client authentication

**Initial login**

Log in using the admin account created during server startup:

```bash
iagctl login admin
```

Follow the prompts to:

1. Enter `admin` when prompted for the initial password.
2. Create a new password when prompted. Your password must be longer than 8 characters.
3. Follow the remaining prompts to finish logging in.

**Subsequent logins**

```bash
iagctl login username
```

## Verify configuration

Verify your client configuration:

```bash
iagctl version --show-config
```

The expected output shows your active terminal configuration, including values from the configuration file and overriding environment variables.

## Client operations

Once configured and authenticated, you can perform various client operations:

```bash
# List services
iagctl get services

# Create a repository
iagctl create repository example-repo --url https://github.com/example/repo.git

# Create a service
iagctl create service python-script my-service --repository example-repo --filename main.py

# Run a service
iagctl run service python-script my-service --set key=value
```

For more information, see [Command reference](./iagctl/cert-gen).

## Manage multiple cluster connections

If you manage multiple gateway clusters from a single workstation, use client profiles to switch between connection configurations without editing `gateway.conf` or setting environment variables between commands. For more information, see [Configure client profiles](./configure-client-profiles).

## Troubleshooting client configuration

**Connection Issues**:

* Verify server hostname/IP accessibility
* Check firewall rules for port 50051
* Confirm TLS configuration matches server settings
* Ensure mutual TLS certificates are properly configured on both client and server

**Authentication Issues**:

* Ensure correct username and password
* Check API key expiration (default 24 hours)
* Verify client has necessary permissions
* Confirm mutual TLS certificate validation is working

**Configuration Issues**:

* Use `iagctl --verbose` for detailed logging
* Check configuration file syntax
* Verify certificate file paths and permissions
* Ensure the correct configuration sections are being applied to the appropriate node types

> Configure client nodes to interact with gateway servers for resource management and service execution.