> For the complete documentation index, see [llms.txt](https://docs.natoma.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.natoma.ai/hidden/on-prem-helm.md).

# Deploy Natoma On-Prem (Helm)

Deploy the Natoma on-premises agent using a Helm chart on Kubernetes, connecting to your self-hosted MCP servers.

This guide covers deploying the Natoma agent on-premises using a Helm chart. The on-prem agent connects to the Natoma cloud control plane for orchestration while routing all MCP traffic within your own infrastructure.

***

## Prerequisites

* A running Kubernetes cluster with Helm installed
* Access to the Natoma tenant admin panel with Admin permissions
* Network access to Docker Hub (or your internal registry) to pull the Natoma agent image

***

## Network Requirements

You may need to allowlist both inbound and outbound traffic depending on your network configuration.

| Type           | IP Address       | Notes                                                                                             |
| -------------- | ---------------- | ------------------------------------------------------------------------------------------------- |
| Natoma egress  | `35.247.116.223` | May not be utilized for on-prem since traffic will always be unidirectional from agent to Natoma. |
| Natoma ingress | `34.49.218.52`   | Agents will make calls to the Natoma API and auth server.                                         |

***

## Agent Image & Helm Chart

Natoma agent images are hosted on **Docker Hub** and **AWS ECR**. Pull commands for Docker Hub are shown below. Contact the Natoma team for ECR access or alternative registry details.

{% hint style="info" %}
If your Kubernetes cluster cannot reach Docker Hub directly, host the agent image in an internal registry and point `image.repository` at your internal path.
{% endhint %}

```bash
# Authenticate into Docker using the token provided by Natoma
echo "dkcr_oat_xxxxx" | docker login registry-1.docker.io \
  -u natomalabs --password-stdin

# Pull the Natoma agent image (confirm the latest version with the Natoma team)
docker pull natomalabs/agent:0.0.8
```

```bash
# Authenticate into Helm using the token provided by Natoma
echo "dckr_oat_xxxxx" | helm registry login registry-1.docker.io \
  -u natomalabs --password-stdin

# Pull the Helm chart
helm pull oci://registry-1.docker.io/natomalabs/natoma-helm
```

***

## Setup

### Step 1: Retrieve On-Prem Credentials

1. In your Natoma tenant admin panel, navigate to **Admin Settings**.
2. Create a new set of on-premise credentials.
3. Copy the **Client ID** and **Client Secret** — you will need both when configuring the Helm chart.

{% hint style="warning" %}
Store the Client ID and Client Secret securely. You will reference these values in your Helm configuration.
{% endhint %}

### Step 2: Create an On-Prem MCP Server

1. In the Natoma web app, navigate to **Apps**.
2. Add a new custom app and set the **Source Type** to **Remote URL**.
3. Check the option **This is an on-prem server**.
4. Enter the remote URL pointing to your on-prem MCP server, appending the `/mcp` suffix to the URL.

### Step 3: Configure and Deploy the Helm Chart

See the [Helm Configuration](#helm-configuration) reference below for full details on all supported values. At minimum, supply the required parameters at install time.

### Step 4: Verify Tool Scanning

Once the agent is deployed and running, Natoma automatically detects it and initiates tool scanning. Each time the on-prem agent polls the Natoma cloud server, any pending scan requests are processed alongside the polling data — no additional configuration is required.

***

## Helm Configuration

### Required Values

The following properties must be provided at install time for the agent to connect to Natoma's cloud services and serve MCP traffic.

#### `natoma.clientID`

The Client ID generated within the Natoma web application for this clustered deployment.

#### `natoma.clientSecret.*`

Contains `secretName` and `secretKey` properties pointing to the Kubernetes secret that holds the Natoma client secret. The defaults expect a secret named `natoma` with a `client-secret` key.

Create the secret with:

```bash
kubectl create secret generic natoma \
  --from-literal=client-secret=<your-client-secret-here>
```

#### `ingress.host`

The hostname through which MCP traffic will be routed. This must be routable and resolvable by all end-users who will connect to MCP servers through the Natoma agent.

#### `image.repository`

Full image name including the repository path. If using the Natoma-hosted image, contact the Natoma team for guidance.

#### `image.tag`

A specific version tag for the agent image. This value will differ if you are self-hosting the image.

***

### Optional Values

The following properties can be configured for more flexible or complex deployments. For help, reach out to the Natoma team or email <support@natomahq.com>.

#### `replicaCount`

Configured number of replicas for the agent service. Ignored when `autoscaling.enabled: true`.

Default: `2`

#### `autoscaling.enabled`

Set to `true` to configure and enable horizontal pod autoscaling.

Default: `false`

#### `autoscaling.minReplicas`

Minimum number of service replicas available during periods of low activity.

Default: `1`

#### `autoscaling.maxReplicas`

Maximum number of service replicas available for scaling.

Default: `8`

#### `autoscaling.targetCPUUtilizationPercentage`

CPU utilization percentage to target for horizontal scaling.

Default: `80`

#### `natoma.logLevel`

Supported values: `debug`, `info`, `warn`, `error`. Leave at `info` during production use unless advised otherwise by Natoma support for troubleshooting.

Default: `info`

#### `natoma.extraCACerts.*`

Enables the Natoma agent process to validate certificates from MCP servers that rely on an internal root CA. Configure the root certificates in a Kubernetes ConfigMap containing a single PEM-formatted file.

Create the ConfigMap with:

```bash
# This example assumes the required certificate is called internal-ca.pem
kubectl create configmap extra-certs --from-file=/path/to/internal-ca.pem
```

Set `natoma.extraCACerts.configMap` to `extra-certs` and `natoma.extraCACerts.key` to `internal-ca.pem`.

#### `ingress.enabled`

Set to `false` to disable the default `Ingress` resource. This may be necessary for complex networking environments or certain managed Kubernetes providers.

Default: `true`

#### `ingress.tls.secretName`

Name of a Kubernetes Secret containing a `crt` key (full certificate chain) and a `key` key (certificate private key).

Create the secret with:

```bash
kubectl create secret generic example-tls \
  --from-file=crt=/path/to/fullchain.crt --from-file=key=/path/to/privkey.key
```

Set `ingress.tls.secretName` to `example-tls`.

#### `ingress.tls.hosts`

When TLS is required, a string array of hostnames matching the certificate's CN and any DNS Alternative Names. Specify using `{}` notation via the Helm CLI:

```bash
--set ingress.tls.hosts={example-natoma.local}
```

#### `ingress.annotations.*`

Optional annotations to configure on the Ingress resource. May be necessary to control behavior within managed Kubernetes providers. Escape `.` characters when passing via the Helm CLI:

```bash
--set ingress.annotations."kubernetes\.io/ingress\.class"=nginx
```

***

## Sample `values.yaml`

```yaml
natoma:
  clientId: "your-client-id-here"
  clientSecret:
    secretName: natoma
    secretKey: client-secret

replicaCount: 2

image:
  repository: <repository-host.com/repository>
  pullPolicy: IfNotPresent
  # Leave empty to default to .Chart.AppVersion
  tag: "0.0.1"

service:
  type: ClusterIP
  port: 9090

ingress:
  enabled: true
  host: natoma-example.local
  tls: []
  annotations: {}

readinessProbe:
  httpGet:
    path: /healthz
    port: 9090
```

***

## Support

Please reach out to the Natoma team or email <support@natomahq.com>.