Skip to navigation
GroundX On-Prem

GroundX On-Prem on AWS

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)
  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 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)
  • AWS CLI (Setup Docs)
  • kubectl (Setup Docs)

1) Defining the Infrastructure

Clone the infrastructure repository:

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

Create the infrastructure configuration file:

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:

./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:

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:

./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:

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:

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")

The client works similarly to a client connected to hosted GroundX. See the API Documentation for endpoint details and tutorials.

Protected file prerequisites

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.