# I tried running HOOPS AI V1.1 headless on Ubuntu 24.04 (EC2) **URL:** https://forum.techsoft3d.com/t/i-tried-running-hoops-ai-v1-1-headless-on-ubuntu-24-04-ec2/5165 **Category:** HOOPS AI **Tags:** how-to, knowledge-base, sample, learn **Created:** [June 24, 2026, 6:59am UTC](https://forum.techsoft3d.com/t/i-tried-running-hoops-ai-v1-1-headless-on-ubuntu-24-04-ec2/5165 "2026-06-24T06:59:22Z") **Posts on this page:** 1 **Page:** 1
### Author: ![Toshi-TS3D](https://sea2.discourse-cdn.com/flex020/user_avatar/forum.techsoft3d.com/toshi-ts3d/32/885_2.png) [@Toshi-TS3D](https://forum.techsoft3d.com/u/Toshi-TS3D) #### Post date: [June 24, 2026, 6:59am UTC](https://forum.techsoft3d.com/t/i-tried-running-hoops-ai-v1-1-headless-on-ubuntu-24-04-ec2/5165/1 "2026-06-24T06:59:22Z")
# I tried running HOOPS AI V1.1 headless on Ubuntu 24.04 (EC2) HOOPS AI V1.1 added Linux support, which is great news if you’re deploying to servers instead of workstations. But most server deployments are headless — no display attached — and Linux support doesn’t necessarily mean _headless_ Linux support. So I wanted to find out: can you actually run it on a headless box today? Short answer: it runs. Here’s how. > **Status note:** Linux is supported as of V1.1. The main thing to know is that license validation and inference still expect an OpenGL/display context to exist, so you’ll need Xvfb to satisfy that on a box with no real display attached. Here’s exactly what that looked like for me. ## 1. Launch the EC2 instance - AMI: Ubuntu Server 24.04 LTS (HVM) - Instance type: choose based on your inference workload (GPU instance if you’re running MFR inference at scale; a general-purpose instance is fine for light/dev use) - Storage: size according to your CAD dataset + FAISS index size - Security group: open only the ports you actually need exposed. If your HOOPS AI instance holds confidential 3D model data or proprietary ML training data, don’t open those ports to `0.0.0.0/0` (all IPs) — restrict access to your own IP range, a VPN, or a bastion host instead SSH in once it’s running: ```auto ssh -i your-key.pem ubuntu@ ``` ## 2. Install required system packages HOOPS AI needs OpenGL and offscreen rendering libraries even when nothing will ever be displayed: ```auto sudo apt-get update && sudo apt-get install -y libglu1-mesa libgl1 libosmesa6 xvfb python3.12-venv p7zip-full ``` | Package | Why it’s needed | | --- | --- | | `libglu1-mesa`, `libgl1` | OpenGL runtime libraries HOOPS AI links against | | `libosmesa6` | Offscreen Mesa rendering (software GL, no GPU/X server needed for rendering itself) | | `xvfb` | Virtual framebuffer X server — lets HOOPS AI think a real display exists | | `python3.12-venv` | Needed to create an isolated virtual environment for the HOOPS AI install (Ubuntu 24.04 ships Python 3.12, and the system Python is externally-managed, so `venv` is required) | | `p7zip-full` | Some assets/sample data used by the WebAPI Sandbox are distributed as `.7z` archives, which aren’t extractable with the default Ubuntu toolset | ## 3. Create the install directory and set ownership Create the directory HOOPS AI will be installed into, then make sure your non-root user actually owns it — otherwise later steps (venv creation, package install, runtime writes) will hit permission errors: ```auto sudo mkdir -p /var/HOOPS_AI/ sudo chown -R ubuntu:ubuntu /var/HOOPS_AI/ ``` ## 4. Install HOOPS AI itself With the install directory ready and owned by your user, set up a venv and install HOOPS AI into it: ```auto cd /var/HOOPS_AI/ python3.12 -m venv .venv source .venv/bin/activate # pip install ``` ### Get the Tutorial Data Assets The SDK install doesn’t include the trained model files used by the tutorials/sandbox — those come as a separate download, the **Tutorial Data Assets** package. You’ll need this for things like the pretrained MFR model (`packages\trained_ml_models\ts3d_162k_mfr.ckpt`). Get the Tutorial Data Assets package separately, then place the whole `packages` folder under your HOOPS AI install directory: ```auto # after downloading/extracting the Tutorial Data Assets package mv packages /var/HOOPS_AI/packages ``` So you end up with, for example, `/var/HOOPS_AI/packages/trained_ml_models/ts3d_162k_mfr.ckpt`. ### Clone the WebAPI Sandbox Instead of working through the raw tutorial notebooks, I switched to the [HOOPS AI WebAPI Sandbox](https://github.com/toshi-bata/hoops_ai_webapi_sandbox) — a ready-to-run sandbox for exercising the HOOPS AI Web API: ```auto sudo git clone https://github.com/toshi-bata/hoops_ai_webapi_sandbox.git /var/hoops_ai_webapi_sandbox sudo chown -R ubuntu:ubuntu /var/hoops_ai_webapi_sandbox ``` (The clone itself doesn’t need `sudo` once `/var/hoops_ai_webapi_sandbox`’s parent is writable by your user — but if you do run it with `sudo` as above, don’t skip the `chown`, or you’ll end up with root-owned files that cause permission errors later.) Set up the environment by following the sandbox’s own `README` (dependencies, `.env` config, etc. — nothing headless-specific at this stage). ### Starting the server headless The sandbox’s normal startup command assumes a display is available. On a headless server, start a virtual display with Xvfb first, then launch the server with `DISPLAY` pointed at it: ```auto cd /var/hoops_ai_webapi_sandbox Xvfb :99 -screen 0 1280x960x24 & DISPLAY=:99 /var/HOOPS_AI/.venv/bin/python main.py --host 0.0.0.0 --port 8000 ``` ### Confirming it worked If the setup is correct, the server startup log should include something like this: ```auto ------------------------------------------------------------ HOOPS AI ------------------------------------------------------------ Platform : Linux 6.17.0-1017-aws Architecture : x86_64 Python : 3.12.3 ------------------------------------------------------------ Core : hoops-ai 1.1.0 (build: ed23c84 2026-06-12T13:13:31Z) CAD Access : hoops-exchange 26.2.0 (build: 1e11169 2026-06-12T10:36:38Z) Conversion : hoops-converter 26.1.1 (build: 00dc9f6 2026-06-12T10:22:46Z) Insights : hoops-web-viewer 26.1.1 (build: d30058f 2026-06-12T10:22:25Z) ------------------------------------------------------------ ====================================================================== [OK] HOOPS AI License: Valid ====================================================================== [hoops_ai] License initialized. INFO: Application startup complete. ``` The line to look for is `[OK] HOOPS AI License: Valid` — that’s your confirmation that both the license and the headless display setup are working correctly. After that, you may see a batch of XKEYBOARD warnings like: ```auto The XKEYBOARD keymap compiler (xkbcomp) reports: > Warning: Could not resolve keysym XF86CameraAccessEnable ... Errors from xkbcomp are not fatal to the X server ``` These are safe to ignore — they’re just Xvfb’s keymap compiler complaining about keyboard keys that don’t matter on a headless server with no physical keyboard attached. They don’t affect the server. ## 5. Test it from another machine Once the server is up, the best way to confirm everything actually works end-to-end is to call the REST API — ideally from a different machine than the EC2 instance itself, so you’re testing it the way a real client would. The [sandbox repo](https://github.com/toshi-bata/hoops_ai_webapi_sandbox) has example calls; here are the two I used to sanity-check things, run from Windows using `curl.exe`: **Upload a CAD file and get back B-rep info:** ```auto curl.exe -X POST http://:8000/cad/load -F "file=@C:\temp\nist_ftc_06_asme1_rd_sw1802.SLDPRT" ``` ```auto {"filename":"4042ab786f8e4a1ab5903e4ae840a689_nist_ftc_06_asme1_rd_sw1802.SLDPRT","faces":{"count":144,"types":[0, ... ``` **Run MFR inference on the same file:** ```auto curl.exe -X POST http://:8000/mfr/inference -F "file=@C:\temp\nist_ftc_06_asme1_rd_sw1802.SLDPRT" ``` ```auto {"filename":"a42285e284b247e0b6b3df7243b0981e_nist_ftc_06_asme1_rd_sw1802.SLDPRT","face_count":144,"predictions":[0, ... ``` If both calls return a JSON response like this, the setup is working correctly. (And as a reminder from the EC2 setup step — if you’re testing from outside the instance like this, make sure port 8000 is only opened to your own IP in the security group, not `0.0.0.0/0`, especially if the CAD files involved are confidential.) ## 6. Run it as a systemd service (non-root) Once you’ve confirmed it works, running it manually in your shell every time isn’t great for anything long-running. Wrap it in a systemd service instead — and run it as a non-root user (User=ubuntu, matching the ownership you set up in step 3) so file permissions stay consistent across restarts. Xvfb (virtual display) must run as a separate service, because ExecStartPre waits for the command to exit — a long-running process like Xvfb would cause a timeout. First, create the Xvfb service: ```auto # /etc/systemd/system/xvfb.service [Unit] Description=Virtual Framebuffer X Server After=network.target [Service] Type=simple ExecStart=/usr/bin/Xvfb :99 -screen 0 1280x960x24 Restart=on-failure [Install] WantedBy=multi-user.target ``` Then create the WebAPI service, declaring a dependency on Xvfb: ```auto # /etc/systemd/system/hoops-ai-sandbox.service [Unit] Description=HOOPS AI WebAPI Sandbox After=network.target xvfb.service Requires=xvfb.service [Service] Type=simple User=ubuntu WorkingDirectory=/var/hoops_ai_webapi_sandbox Environment=DISPLAY=:99 ExecStart=/var/HOOPS_AI/.venv/bin/python main.py --host 0.0.0.0 --port 8000 Restart=on-failure [Install] WantedBy=multi-user.target ``` Enable and start both services: ```auto sudo systemctl daemon-reload sudo systemctl enable --now xvfb.service sudo systemctl enable --now hoops-ai-sandbox.service sudo systemctl status hoops-ai-sandbox.service ``` ## Summary | Step | Required? | | --- | --- | | Install `libglu1-mesa libgl1 libosmesa6 xvfb python3.12-venv p7zip-full` | Yes | | Create install dir and `chown -R ubuntu:ubuntu` it | Yes — avoids permission errors during install/runtime | | Start Xvfb + set `DISPLAY` | Yes — license validation/inference won’t start without it | | Test via REST API from another machine | Recommended — confirms the setup end-to-end | | Run service as non-root user | Yes — keeps file permissions consistent | If you want more detail on how the WebAPI Sandbox itself is built, I wrote that up separately in [Wrapping HOOPS AI as a REST API with FastAPI](https://forum.techsoft3d.com/t/wrapping-hoops-ai-as-a-rest-api-with-fastapi/5168). ## Verdict It runs once Xvfb is in the picture — that part’s straightforward, and otherwise it’s a clean path from EC2 instance to working API. Happy to answer questions or share my exact systemd unit / install steps if useful — let me know in the comments.