Skip to main content

Quick start

This guide walks you through trialing Faheem Code Enterprise on your own infrastructure. You'll provision infrastructure (AWS Terraform or a manual VM setup), configure GitHub for user authentication, and configure your LLM provider.

Who this is for​

This guide is not for single-user local laptop installs. It is for a 30-day trial of Faheem Code Enterprise on a dedicated VM/server on your own infrastructure. The deployment requires DNS records, network, and compute setup before installation.

If you want to use Faheem Code immediately without infrastructure setup:

  • Use Faheem Code Cloud (SaaS)
  • Run Faheem Code locally using Docker, the CLI or the SDK

Accounts and credentials​

Before you begin, make sure you have the following ready:

Register for a trial account

Sign up for a free 30-day Faheem Code Enterprise trial account. You'll need this to access the installer dashboard.
  • LLM credentials from your chosen provider, for example an Anthropic API key from the Anthropic Console
  • A GitHub account with permission to create GitHub Apps
  • An AWS account with permissions to create EC2, VPC, and Route53 resources (if using the AWS with Terraform path)

Provision infrastructure​

You will need a VM to host Faheem Code Enterprise. Choose one of the options below to provision your infrastructure.

We provide a Terraform module that provisions a properly configured environment for Faheem Code Enterprise, including the EC2 instance, DNS records, and TLS certificates.

Faheem Code AWS Terraform module

Follow the README instructions to configure and apply the Terraform configuration.

Preflight validation​

All items below must be completed before running the installer:

  • VM meets CPU, memory, disk, and OS requirements
  • DNS records are created and resolve from the VM
  • Inbound ports are open: 80, 443, and 30000
  • Outbound domains are reachable from the VM
  • GitHub App prerequisites are prepared
  • (Optional) External PostgreSQL instance provisioned if using your own database

DNS checks​

Run the checks below on the target VM before opening the installer dashboard.

Export your base domain:

export BASE_DOMAIN="faheem-code.example.com"

Test DNS:

for h in "admin.${BASE_DOMAIN}" "app.${BASE_DOMAIN}" "test-runtime.${BASE_DOMAIN}"; do
  echo "[DNS] $h"
  getent hosts "$h" || nslookup "$h"
done

Expected: each hostname resolves to your VM's public IP address through the wildcard record.

Outbound connectivity checks​

urls=(
  "https://replicated.app"
  "https://proxy.replicated.com/v2/"
  "https://images.r9.faheemcode.ai/v2/"
  "https://install.faheemcode.ai"
  "https://charts.r9.faheemcode.ai"
  "https://updates.r9.faheemcode.ai"
  "https://github.com"
  "https://traefik.github.io/charts/index.yaml"
  "https://registry-1.docker.io/v2/"
  "https://ghcr.io/v2/"
)

for u in "${urls[@]}"; do
  # HTTP 000 means connection failure (DNS failure, timeout, or blocked network path).
  code=$(curl -sSIL --max-time 15 -o /dev/null -w "%{http_code}" "$u" || true)
  if [ "$code" = "000" ]; then
    echo "FAIL $u"
  else
    echo "OK   $u (HTTP $code)"
  fi
done

Any HTTP response code other than 000 is acceptable for reachability checks (for example 200, 301, 302, 401, 403, 405).

If any check fails, stop and resolve before continuing:

  • DNS failures: Verify records are created, point to the right target, and have finished propagating
  • Outbound connectivity failures: Check firewall egress rules, proxy settings, and TLS inspection policies

Reasons for requirements​

RequirementWhy It Exists
443/TCP inboundPrimary HTTPS entrypoint for users and service hostnames
30000/TCP inboundReplicated/KOTS Admin Console for install and configuration
80/TCP inboundHTTP entrypoint used for ingress/redirect behavior
*.<domain> DNS + cert SANApplication services and sandboxes are addressed by hostnames under the base domain
replicated.app, proxy.replicated.comReplicated control-plane/license/install paths
images.r9..., charts.r9..., updates.r9..., install.r9...Vendor distribution image/chart/update/install endpoints
traefik.github.ioEmbedded cluster ingress chart repository
ghcr.io, registry-1.docker.ioContainer image pulls for platform components
github.comGitHub App setup/auth/webhooks and downloading public agent skills

Run the installer​

1. Access the installer dashboard​

After preflight validation checks have passed, register for a free 30-day trial, then log in to the installer dashboard. You will see the dashboard below. Click "View install guide" in the Install tile.

Screenshot: Installer Dashboard.

2. Name your instance​

Enter a name for your instance (e.g., your company name or environment identifier). Select "Outbound requests allowed" for Network Availability, then click Continue.

Screenshot: Instance name and network availability.

3. Run the installation commands​

The install guide provides commands to run on your VM. SSH into your VM and execute them in order:

  1. Select a version -- the latest version is pre-selected
  2. Download the installation assets -- copy and run the curl command shown
  3. Extract the installation assets -- run the tar command shown (this includes your license file)
  4. Install -- run the install command shown

If the install command fails after preflight checks pass, see Troubleshooting to generate a support bundle and open a support ticket.

Screenshot: Installation commands.

4. Access the Admin Console​

Once the install command completes, the Admin Console is available at:

  • https://admin.<your-base-domain>:30000 (if you provided TLS certificates)
  • http://<your-vm-ip>:30000 (if you did not use the --tls-cert and --tls-key flags on the install command)

If you did not provide TLS certificates with the install command, your browser will display a security warning. Click Advanced, then Proceed to continue to the Admin Console.

Screenshot: Self-signed certificate warning.

5. Upload TLS certificate (if not provided with the install command)​

If you did not provide certificates with the install command, select "Upload your own", enter admin.<your-base-domain> under Hostname, upload your private key and SSL certificate, then click Continue.

If you upload a private CA certificate, make sure any external webhook or OAuth provider that calls Faheem Code also trusts that CA.

Screenshot: Upload TLS certificate.

6. Log in to the Admin Console​

Enter the password you set during installation and click Log in.

Screenshot: Admin Console login.

7. Configure the cluster​

You will be prompted to add additional nodes to the cluster. For a single-node deployment, click Continue to skip this step.

Screenshot: Configure cluster nodes.

Configure Faheem Code​

You should now see the application configuration page.

Screenshot: Configure Faheem Code.

Domain configuration​

  • Keep the Hostname Configuration Mode set to "Simple (default)"
  • Enter your base domain (e.g., faheem-code.example.com)

Certificate configuration​

  • Upload your TLS Certificate (.crt or .pem)
  • Upload your TLS Private Key (.key or .pem)
  • Optionally upload the root CA Certificate for your TLS certificates

LLM configuration​

Choose an LLM provider from the LLM Configuration dropdown and enter the details from that provider.

Screenshot: LLM Configuration provider dropdown.

For example, if you use Anthropic, enter your API key from the Anthropic Console.

Database configuration​

By default, Faheem Code Enterprise uses a bundled PostgreSQL database. If you need to use your own PostgreSQL instance (for example, to integrate with existing database infrastructure or meet specific backup/HA requirements), see External PostgreSQL for setup instructions.

GitHub authentication​

Enable GitHub Authentication in the Admin Console, then follow these steps to create and configure a GitHub App.

Create a GitHub app​

Run our script to create a GitHub App configured for your install.

Map GitHub app values to Admin Console​

Go back to the Installer Admin Console in your browser and enter the values from the Create GitHub App script output. For the private key, upload the file from the keys directory of the script location.

See GitHub for GitHub App installation, @faheem-code resolver behavior, pull request review identity, and repository-level review controls.

Additional integrations​

If your team uses Jira Data Center or Bitbucket Data Center, follow these guides to configure Admin Console values before deployment and complete webhook setup inside Faheem Code after deployment.

Bitbucket Data Center

Configure Bitbucket Data Center login, repository access, bot identity, and pull request webhooks.

Jira Data Center

Configure Jira issue triggers, OAuth account linking, service account credentials, and Jira webhooks.

After filling in all fields, click Continue at the bottom of the page.

Deploy and verify​

Faheem Code will begin deploying. You can expect the deployment status to transition from Missing to Unavailable to Ready. This typically takes 5-10 minutes.

Screenshot: Deployment in progress.

Click Details next to the deployment status to monitor individual resources. Resources shown in orange are still deploying -- wait until all resources are ready.

Screenshot: Deployment status details.

First login​

Once the deployment status shows Ready, navigate to https://app.<your-base-domain> and click the Login with GitHub tile.

Accept the Terms of Service and click Continue.

Screenshot: Accept Terms of Service.

Faheem Code Enterprise is now running. You can open a repository or start a new conversation.

Screenshot: Faheem Code is ready.

Next steps​

Enterprise overview

Learn about Faheem Code Enterprise features, integrations, and deployment options.

Prompting best practices

Get the most out of your AI coding agents with effective prompting techniques.

Troubleshooting

Collect diagnostics, inspect workloads, and contact Faheem Code Support.

Faheem Code documentation

Explore the full Faheem Code documentation for usage guides and features.