CodeNavi on a cloud GPU VM (AWS, Google Cloud)¶

The standard trial install runs unchanged on a GPU virtual machine in your own cloud account. This page is the verified recipe for the two hyperscalers we test on — one L4 instance each — with the measured timings, the host preparation each image needs, and how to reach the server from your workstation without exposing it to the internet.

It is the full product on the VM: index, search, MCP endpoint, updates. If you only want to build an index on rented GPU time and run the server elsewhere, see Cloud reindex.

Licence: a VM in your own AWS or Google Cloud account — your account, your root login, your lifecycle — is infrastructure you control, so this is ordinary self-hosting under the standard licence; no addendum is required. The rented-GPU addendum on Rented GPUs applies only where a third party operates the host (marketplaces such as vast.ai, RunPod, Hyperstack).

What was verified¶

Both lanes ran the trial one-liner from the portal email on a fresh VM, indexed the public laravel/framework repository (3,243 files after skips), ran the 40-case MCP smoke suite, and confirmed the connected update channel.¹

	AWS `g6.xlarge`	Google Cloud `g2-standard-4`	Google Cloud `g2-standard-4`
GPU	NVIDIA L4, 24 GB	NVIDIA L4, 24 GB	NVIDIA L4, 24 GB
Image	Deep Learning AMI, Ubuntu 22.04	Deep Learning VM, Ubuntu 22.04, driver 580	Rocky Linux 9 + NVIDIA 580
Engine	Docker (preinstalled)	Docker CE (installed by hand)	rootless Podman 5.8, SELinux Enforcing
Image download (7.6 GB)	5m06s	5m29s	not timed
Image load	4m03s	3m49s	6m02s
Server ready after start	1m03s	59 s	~55 s (started by hand, see snags)
Full reindex, 3,243 files / 33k chunks	1420 s	1444 s	1453 s
MCP smoke	29 passed, 0 failed	29 passed, 0 failed	29 passed, 0 failed

The reindex time is the same on both clouds within two percent — it is the L4, not the provider. The only provider-dependent number is the image download from our CDN. A fresh install plus a first reindex of a repository this size fits inside one billable hour; check your provider's calculator for the instance price in your region.

Before you start¶

A trial or licence link from the portal — the one-liner in the email is the whole install. The link's download window is 48 hours from first use.
Disk: 100 GB or more free on the VM. The installer needs about four times the 7.6 GB image plus headroom for the layer cache it keeps for updates; the deep-learning images themselves are large. We use 200 GB.
Network posture: allow SSH from your own IP only. Do not open port 8765 to the internet — reach it through an SSH tunnel (below) or your private network.
CPU-only cloud instances are not a shortcut — indexing on CPU is impractical at any size beyond a toy repository; see GPU compatibility.

AWS — `g6.xlarge`¶

Launch a g6.xlarge from the AWS Deep Learning AMI (Ubuntu 22.04). It ships the NVIDIA driver, Docker, and the NVIDIA container toolkit — nothing to install. Give it a 200 GB gp3 root volume and a security group that allows TCP 22 from your IP only. An Elastic IP saves you a changing address across stop/start.
SSH in as ubuntu and run the one-liner from your portal email, pointing it at the repository you want indexed:

git clone --depth 1 https://github.com/your-org/your-repo ~/repos/your-repo
export CODEBASE_PATH=$HOME/repos/your-repo
curl -fsSL https://codenavi.com/trial/install/<token> | sh      # the line from your email

Eleven steps, about fifteen minutes end to end on this instance. The closing screen prints the MCP auth token — copy it somewhere private, it is not written to any log. 3. Stop the instance when idle (aws ec2 stop-instances); storage is the only charge while stopped, and the install comes back with the instance.

AWS in one step — CloudFormation¶

The same three steps as one stack: codenavi-ec2.yaml creates a small VPC, a security group that allows SSH from your address only, and the g6.xlarge above from the Deep Learning Base AMI (resolved for your region automatically), then runs the install one-liner at first boot with the repository you name. Measured on a g6.xlarge with the default gp3 volume: the stack is up in under a minute and the first-boot install takes about 35 minutes (5.5 min image download, 8 min image load, 15 min building the update cache — the step that makes later updates small — and 3 min model warm-up), then a first reindex.

Download the template and open CloudFormation → Create stack → Upload a template file (or aws cloudformation create-stack --template-body file://codenavi-ec2.yaml …).
Fill in the parameters: your install token (the 32 characters after /trial/install/ in the portal's Install CodeNavi command or your trial email), the HTTPS URL of the repository to index (public, or private with a read token in the URL), your public IP as a /32, and an existing EC2 key pair. The token and the URL are NoEcho parameters — they do not appear in the stack's outputs or events.
When the stack reads CREATE_COMPLETE, the instance is still installing. SSH in with the SshCommand output and watch tail -f ~/codenavi-install.log; it ends with the installer's closing screen. The MCP auth token is in ~/codenavi/.env (CODENAVI_AUTH_TOKEN) — it is written nowhere else.
Open the TunnelCommand from your workstation and visit http://localhost:18765/connect to build the index and wire your agent.

Delete the stack to remove everything it created; stop the instance to pause it. Nothing in the template phones home beyond what the installer itself does (Updating).

Google Cloud — `g2-standard-4`¶

Two images are verified. Both need a one-time host step the AWS image does not.

Google Cloud in one step — startup script¶

Google has no CloudFormation equivalent that a customer is sure to have, so the one-step shape here is gcloud plus a startup script we publish: codenavi-gce-startup.sh. The VM runs it as root at first boot: it installs Docker (the step 2 below does by hand), creates a codenavi login user, clones your repository and runs the install one-liner. Your token and repository URL travel as instance metadata. Measured first boot on a g2-standard-4 with a 200 GB pd-balanced disk: about 17 minutes from VM creation to the closing screen (driver check and Docker install 1 min, download 4–6 min, image load 4 min, update cache 3 min, model warm-up 1 min). Fill in the first line and paste the block:

PROJECT=my-project REGION=us-central1 ZONE=us-central1-a MY_IP=203.0.113.4/32 \
TOKEN=<install token> REPO=https://github.com/org/repo.git
curl -fsSLO https://codenavi.com/docs/cloud/codenavi-gce-startup.sh
gcloud compute networks create codenavi --project $PROJECT --subnet-mode custom
gcloud compute networks subnets create codenavi-sub --project $PROJECT --network codenavi \
  --region $REGION --range 10.43.0.0/24
gcloud compute firewall-rules create codenavi-ssh --project $PROJECT --network codenavi \
  --allow tcp:22 --source-ranges $MY_IP --target-tags codenavi
gcloud compute instances create codenavi --project $PROJECT --zone $ZONE \
  --machine-type g2-standard-4 --accelerator type=nvidia-l4,count=1 --maintenance-policy TERMINATE \
  --image-family common-cu129-ubuntu-2204-nvidia-580 --image-project deeplearning-platform-release \
  --boot-disk-size 200GB --boot-disk-type pd-balanced \
  --network codenavi --subnet codenavi-sub --tags codenavi \
  --shielded-secure-boot --shielded-vtpm --shielded-integrity-monitoring \
  --no-service-account --no-scopes \
  --metadata install-nvidia-driver=True,codenavi-token=$TOKEN,codenavi-repo=$REPO \
  --metadata-from-file startup-script=codenavi-gce-startup.sh

The token is the 32 characters after /trial/install/ in the portal's Install CodeNavi command or your trial email; a private repository takes a read token in its URL (https://[email protected]/org/repo.git). Both sit in the instance's metadata — readable by anyone who can view the instance in your project, so treat project access accordingly.

Then: gcloud compute ssh codenavi --project $PROJECT --zone $ZONE and sudo tail -f /opt/codenavi/codenavi-install.log — it ends with the installer's closing screen. (gcloud logs you in under your workstation username; if that happens to be codenavi, pick another — gcloud compute ssh me@codenavi … — so it does not land on the install user.) The MCP auth token is in /opt/codenavi/codenavi/.env (CODENAVI_AUTH_TOKEN), nowhere else. For the tunnel from your workstation: gcloud compute ssh codenavi --project $PROJECT --zone $ZONE -- -N -L 18765:localhost:8765, then open http://localhost:18765/connect. Delete the four resources in reverse order to remove everything; gcloud compute instances stop pauses it.

Quota and account notes. A new project has a default quota of one L4 per region; a second VM goes in a second region. If the project has no default Compute Engine service account, create the VM with --no-service-account --no-scopes — CodeNavi needs no Google API access.

Ubuntu + Docker¶

Create the VM from image family common-cu129-ubuntu-2204-nvidia-580 (project deeplearning-platform-release): g2-standard-4, one nvidia-l4, 200 GB boot disk, your own VPC with a firewall rule for TCP 22 from your IP. The driver must be 570.65 or newer — older families ship a 550 driver and CUDA fails to initialise.
Install Docker. This image ships the driver and the NVIDIA container toolkit but no Docker engine. Take Docker CE from Docker's own repository, then wire the runtime:

sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo nvidia-ctk runtime configure --runtime=docker && sudo systemctl restart docker
sudo usermod -aG docker "$USER"     # then log out and back in

Do not add NVIDIA's container-toolkit apt repository on this image — its pinned toolkit 1.19 conflicts with the newer package and apt refuses with unmet dependencies. The preinstalled toolkit is fine. 3. Run the one-liner exactly as in the AWS step above.

Rocky Linux 9 + Podman¶

The RHEL-family shape: rootless Podman, SELinux Enforcing, no Docker anywhere. The shipped compose overlays run the container on the GPU with no SELinux changes on the host.

Create the VM from image family rocky-linux-9-optimized-gcp-nvidia-580 (project rocky-linux-accelerator-cloud), same shape as above. It ships the driver only.
Prepare the host as on the Podman page — Podman from the base repository, the compose provider from PyPI (EPEL's podman-compose 1.5 cannot render CodeNavi's compose file), the NVIDIA toolkit from NVIDIA's repository, and the CDI spec:

sudo dnf install -y podman epel-release git && sudo dnf install -y pipx
pipx install podman-compose                    # 1.6 — into ~/.local/bin
curl -fsSL https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo \
  | sudo tee /etc/yum.repos.d/nvidia-container-toolkit.repo >/dev/null
sudo dnf install -y nvidia-container-toolkit
sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml
nvidia-ctk cdi list                            # expect nvidia.com/gpu=all
loginctl enable-linger "$USER"                 # keeps the container alive after logout

Run the one-liner as above. The installer detects Podman, uses its docker-compatible socket, writes the rootless UID mapping, and stacks the CDI overlay so the container asks for the GPU the way Podman understands.

Reaching the server from your workstation¶

Port 8765 stays closed at the firewall. Open a tunnel and point your agent at the local end:

ssh -N -L 18765:localhost:8765 ubuntu@<vm-ip>        # rocky@ on the Rocky image
# then, in your agent's MCP config:  http://localhost:18765/mcp

Round-trip latency to a US region from Europe adds about half a second to every search; the search itself is warm at that point. A private network (a VPN or mesh overlay between the VM and your workstation) removes the tunnel step; the server's own remote access page covers HTTPS in front of it.

To let a coding agent do the install and the wiring for you, hand it the agent setup runbook URL — it was written for exactly this case.

Updates and teardown¶

./update.sh --check and ./update.sh work over the connected channel from the VM like anywhere else; the layer cache the installer primes means an update fetches only the changed layers — about 25 MB for a code-only release.¹

Delete the VM, its disk, and any reserved address when you are done. On AWS a stopped instance still bills its volume and Elastic IP; on Google Cloud the same applies to the disk and a reserved external address.

Snags we hit so you don't¶

Google DLVM, "docker: command not found" — the image has no Docker; see above.
Rocky 9, compose up dies with could not parse mount after a successful-looking install — EPEL's podman-compose 1.5.0. Install 1.6 via pipx; from the next release the installer refuses that provider up front instead.
Rocky 9, a bare podman run --device nvidia.com/gpu=all says NVML: Insufficient Permissions — SELinux. The CodeNavi overlays carry the label override; nothing to change on the host for the install itself.
Google Cloud, Quota 'NVIDIA_L4_GPUS' exceeded. Limit: 1.0 — one L4 per region by default; use another region or request more.
AWS, disk fills during "Cache for updates" on a 100 GB volume — grow it online (growpart + resize2fs) or start at 200 GB.
The first /health after a reindex may answer 503 for a few seconds — the server reloads the index; retry.

Verified 2026-09-12 (AWS, CN-693/CN-697) and 2026-09-13 (Google Cloud, CN-700) on release 1.3.37. The Rocky Linux lane found the provider and messaging defects fixed in CN-702. ↩↩