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

## A Simple Guide to Installing GroundX On-Prem onto AWS

Deploy GroundX On-Prem on AWS to run retrieval augmented generation (RAG) in a controlled environment. The deployment can run without external dependencies, supporting applications with strict security requirements.

GroundX On-Prem is available as:

1. A free, open source repo ([github](https://github.com/eyelevelai/groundx-on-prem))
2. A paid product with additional capabilities
3. A service with dedicated support

This guide uses the free, open source version.

See [Choose Your GroundX Path](/documentation/get-started/choose-your-ground-x-path) to compare deployment options, including managing an on-prem instance with GroundX Agent Harness.

---

**⚠️ Warning ⚠️**

**This guide creates AWS resources that incur charges. Remove the resources when finished. AWS experience is recommended.**

---

### Prerequisites

Install these tools before starting:

* bash shell (version 4.0 or later recommended. AWS Cloud Shell has insufficient resources.)
* terraform ([Setup Docs](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli))
* AWS CLI ([Setup Docs](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html))
* kubectl ([Setup Docs](https://kubernetes.io/docs/tasks/tools/))

### 1) Defining the Infrastructure

Clone the infrastructure repository:

```bash
git clone https://github.com/eyelevelai/eyelevel-iac.git
```

Create the infrastructure configuration file:

```bash
cd eyelevel-iac/
cp environment/aws/env.tfvars.example environment/aws/env.tfvars
```

`env.tfvars` defines the Terraform resources. The copied example uses the default configuration. Edit it to suit your deployment.

Create the infrastructure:

```bash
./environment/aws/setup-eks
```

The command prompts for the AWS region and asks you to confirm the configuration.

After it completes, deploy GroundX on the new infrastructure.

### 2) Deploying GroundX

Create the application configuration file:

```bash
cp operator/env.tfvars.example operator/env.tfvars
```

Edit the copied file before deploying GroundX.

For security, you **MUST** set these values in `operator/env.tfvars`:

* `admin.api_key`: Set a random UUID, generated with `bin/uuid`. This is the admin API key used for inter-service communication.
* `admin.username`: Set a random UUID, generated with `bin/uuid`. This is the admin user ID used for inter-service communication.
* `admin.email`: Set the admin account email address.

Deploy GroundX with the saved configuration:

```bash
./operator/setup
```

This deploys GroundX On-Prem to the Kubernetes cluster created in step 1.

### 3) Setting Up A Client To Talk TO GroundX On-Prem

Run `kubectl -n eyelevel get svc` to find the API endpoint. Use the GroundX load balancer's external IP or hostname.

Example external address:

```text
EXTERNAL-IP
b941a120ecd91455fa7b8682be2a9e41-1427794132.us-east-2.elb.amazonaws.com
```

Configure the SDK with that endpoint and the `admin.api_key` from `operator/env.tfvars`:

**`Python`**

```python title="Python"
from groundx import GroundX

external_ip = "b941a120ecd91455fa7b8682be2a9e41-1427794132.us-east-2.elb.amazonaws.com"
api_key="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

client = GroundX(api_key=api_key, base_url=f"http://{external_ip}/api")
```

**`TypeScript`**

```typescript title="TypeScript"
import { GroundXClient } from "groundx";

const externalIp = "b941a120ecd91455fa7b8682be2a9e41-1427794132.us-east-2.elb.amazonaws.com";
const apiKey = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

const client = new GroundXClient({ apiKey: apiKey, environment: `http://${externalIp}/api` });
```

The client works similarly to a client connected to [hosted GroundX](https://dashboard.eyelevel.ai/auth/login). See the [API Documentation](https://documentation.eyelevel.ai/docs/welcome) for endpoint details and tutorials.

## Protected file prerequisites

[File Access and Sharing](/documentation/fundamentals/file-access-and-sharing) describes the local API contracts. Before enabling file protection, verify:

* Compatible API, processor, and gateway images.
* Private storage origins and reachable signing endpoints with trusted TLS certificates.
* Shared policy, cache, and database services.
* Protection for existing files.

Do not enable protected workflows with an older upload helper that only supports public storage. Test each advertised storage backend at its pinned versions. Verify the deployment's local MCP routes and authentication. Hosted OAuth endpoints do not configure on-prem MCP.