Setting Up Intelliprompter with TypeSafe Jev for Real-Time Speech Scoring
After watching NetworkChuck's video on TypeSafe Jev and exploring the official TypeSafe Intelliprompter cookbook, I paired up with OpenAI Codex across two sessions to turn the single-user cookbook reference into a multi-user, self-hosted container. In this guide, we will start with the exact prompt used to have Codex generate the application from the TypeSafe cookbook and pull its API key from the system keyring, and then deploy the resulting Intelliprompter stack in Docker Compose so TypeSafe Jev (jev-1.13.0 / jev-latest) can evaluate live speech and advance presentation topics automatically.
Traditional teleprompters force you to read a scrolling wall of text word for word, which immediately makes a technical talk or video recording sound robotic. Intelliprompter flips that model on its head: you organize a speech into sequential topics and bulleted talking points, speak naturally in your own words, and let browser speech recognition stream your transcript to TypeSafe Jev. Every few seconds, Jev scores how thoroughly you covered each remaining point on a 1 to 5 scale; as soon as a talking point crosses your configured threshold (default 2.5), Intelliprompter locks that point as complete and automatically advances the presentation overlay to the next topic once the current topic is finished.
Prerequisites
Before starting this build, you need a host with Docker and Docker Compose installed. Next, you will need a Git repository to track your application code and container configuration; you could host your own or use a free account on GitHub or GitLab (I self-host GitLab for the unlimited pipeline quota). Then you need an AI coding agent to scaffold the application from the reference cookbook; any agent will work (Google Antigravity, Claude Code, ChatGPT, or OpenAI Codex; they can all do it). Finally, you need a TypeSafe Jev API key (a minimum $25 credit purchase is required), along with secret-tool (from libsecret-tools) if you want to store and pull the API key from your Linux system keyring.
- Linux host with Docker Engine and Docker Compose installed.
- Git repository for version control (a free account on GitHub or GitLab, or a self-hosted GitLab instance).
- AI coding agent of your choice (Google Antigravity, Claude Code, ChatGPT, or OpenAI Codex).
- TypeSafe Jev API key from typesafe.ai (minimum $25 credit purchase required) and
libsecret-tools(secret-tool) for keyring storage.
Step 1: Store Your API Key in the Keyring and Prompt Codex to Build the App
Before prompting your coding agent to scaffold the application and Docker stack, store your TypeSafe Jev API key in your Linux system keyring using secret-tool so the agent can wire it into .env without you pasting raw secrets into the chat history:
secret-tool store --label="Typesafe Jev API Key" service typesafe.ai purpose jev-intelliprompterNext, give OpenAI Codex (or your preferred coding agent) the reference cookbook URL, the target Docker Compose directory on your container host, the keyring lookup attributes, and the path to your homelab documentation vault:
I want to create a docker container for Intelliprompter on my Proxmox Docker host. We need to create a new Docker Compose stack in /path/to/git/intelliprompter/
It will also need a documentation note in /path/to/docs/containers/intelliprompter.md
The full reference implementation is here: https://docs.typesafe.ai/cookbooks/intelliprompter
I stored the secret API key in the system keyring here: secret-tool store --label="Hermes Typesafe Jev API Key" service typesafe.ai purpose jev-intelliprompter
That value should go into the .env file for the Docker Compose stack.From that starting prompt, Codex fetches the TypeSafe Intelliprompter cookbook, builds the initial FastAPI + Uvicorn backend and browser SpeechRecognition frontend, writes the Dockerfile and Compose configuration, and populates .env from secret-tool lookup service typesafe.ai purpose jev-intelliprompter.
Keep in mind that the initial prompt creates a bare-minimum application based on the single-user cookbook. Immediately after the first build finishes, have Codex start the Docker container locally so you can open it in your browser and test it in person with a microphone. Testing it live will naturally spark a round of follow-up messages (Part 1 Codex session and Part 2 Codex follow-up) as you prompt the agent to layer in the features you want for real presentations:
- Multi-user support with isolated speech libraries and encrypted per-user API keys.
- User roles (
adminvs.userpermissions, plus an admin panel for managing accounts). - Fit-and-finish details for the app such as dark stage themes, progress bar colors, and readable typography.
- Preventing the device screen from locking while a speech is open (
navigator.wakeLock.request("screen")via the Screen Wake Lock API). - Other quality-of-life additions you spot during live testing, such as a real-time Jev score reasoning drawer, manual topic override buttons, and installable mobile PWA manifests.
Step 2: Configure the Intelliprompter Environment and Bootstrap Admin
On your Docker host (ai-host-01), create the deployment directory and persistent SQLite data folder owned by unprivileged UID/GID 10001:10001:
sudo mkdir -p /path/to/git/intelliprompter/data
sudo chown -R 10001:10001 /path/to/git/intelliprompter/dataVerify or create /path/to/git/intelliprompter/.env (populated from your secret-tool lookup service typesafe.ai purpose jev-intelliprompter value) along with your default Jev model, coverage threshold, and bootstrap administrator credentials:
TYPESAFE_API_KEY=ts_live_replace_with_your_typesafe_jev_key
JEV_MODEL=jev-latest
SCORE_THRESHOLD=2.5
INTELLIPROMPTER_DB_PATH=/data/intelliprompter.sqlite3
INTELLIPROMPTER_BOOTSTRAP_ADMIN_USERNAME=admin
INTELLIPROMPTER_BOOTSTRAP_ADMIN_PASSWORD=change_me_to_a_long_admin_password
INTELLIPROMPTER_SESSION_TTL_SECONDS=1209600
INTELLIPROMPTER_HTTPS_ONLY=1Admin accounts can score speeches directly against the server-level TYPESAFE_API_KEY, while standard user accounts store their own personal Jev API tokens inside the SQLite database encrypted with AES-256-GCM using a key wrapped by PBKDF2-SHA256 (600,000 iterations) derived from each user's login password.
Step 3: Deploy the Locked-Down Read-Only Docker Compose Stack
Create /path/to/git/intelliprompter/compose.yaml. Because Intelliprompter only writes to /data/intelliprompter.sqlite3, we run the container with a read-only root filesystem, drop all Linux kernel capabilities, and bind port 8088 on the local LAN interface:
services:
intelliprompter:
image: registry.example.com/homelab/intelliprompter:latest
build:
context: .
dockerfile: Dockerfile
container_name: intelliprompter
restart: unless-stopped
user: "10001:10001"
read_only: true
tmpfs:
- /tmp:size=16m,mode=1777
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
env_file:
- path: .env
required: false
environment:
JEV_MODEL: ${JEV_MODEL:-jev-latest}
SCORE_THRESHOLD: ${SCORE_THRESHOLD:-2.5}
INTELLIPROMPTER_DB_PATH: /data/intelliprompter.sqlite3
INTELLIPROMPTER_HTTPS_ONLY: ${INTELLIPROMPTER_HTTPS_ONLY:-1}
volumes:
- /path/to/git/intelliprompter/data:/data
ports:
- "10.10.20.2:8088:8000"Start the container and verify the unauthenticated health endpoint (which verifies SQLite readiness without consuming any TypeSafe Jev tokens):
cd /path/to/git/intelliprompter
docker compose up -d
curl -s http://10.10.20.2:8088/api/health | jq .Step 4: Structure a Multi-Topic Speech Outline for Jev Evaluation
Intelliprompter parses plain-text outlines into topics and talking points. Any line without a bullet starts a new topic heading, and lines starting with -, *, or numbered prefixes (1.) become scored talking points inside that topic:
Opening Hook: Why Scrolling Scripts Fail
- Explain why reading word-for-word drains energy on camera
- Introduce real-time semantic scoring with TypeSafe Jev
How Jev Scores Live Speech
- Browser speech recognition buffers 20 words or a 3-second pause
- Jev evaluates unchecked points in the active topic on a 1 to 5 scale
- Points scoring 2.5 or higher lock immediately and advance the topic
Self-Hosted Security and Mobile PWA
- Per-user Jev tokens are sealed with AES-256-GCM and PBKDF2-SHA256
- Screen Wake Lock keeps phone displays awake on stageWhen you click Start Presentation, Intelliprompter only evaluates the active topic's remaining points and skips API calls entirely whenever the transcript has not changed since the last evaluation pass.
Step 5: Serve Over HTTPS for Browser Speech Recognition and Screen Wake Lock
Modern desktop and mobile browsers restrict both the Web Speech API (SpeechRecognition / webkitSpeechRecognition) and the Screen Wake Lock API (navigator.wakeLock.request('screen')) to secure contexts (https:// or localhost). Place Intelliprompter behind your reverse proxy (such as Caddy, Traefik, or Cloudflare Tunnel) terminating TLS in front of 10.10.20.2:8088, then open the URL in Chrome on Android or desktop and select Install App from the browser menu to pin Intelliprompter as a standalone Progressive Web App.
Hardware & Gear Used in This Guide
- USB Cardioid Condenser Microphone for Clean Speech Recognition (Amazon Search): Feeds crisp, low-noise audio into browser speech recognition so TypeSafe Jev receives accurate live transcripts even when speaking from arm's length.
- Adjustable Desktop Tablet and Phone Teleprompter Stand (Amazon Search): Positions your phone or tablet right below your camera lens while the Screen Wake Lock keeps the Intelliprompter topic gauges visible.
Disclosure: Some hardware and infrastructure links above are affiliate or referral links that support By Design Won't Fix at no extra cost to you.
What You Can Do Next
- Read the companion story on Frizzle Tech Blog covering how NetworkChuck's video on TypeSafe Jev inspired the project and how I worked with OpenAI Codex (Session 1 and Session 2) to build the per-user token encryption and 90% test coverage gate.
- Tune the
Coverage Thresholdslider between2.0(conversational mentions) and3.5(strict technical detail) depending on whether you are recording an informal vlog or delivering a compliance presentation. - Use Intelliprompter's speech-sharing controls to grant read-only access to co-presenters on your team so they can rehearse the same talking points using their own personal Jev API tokens.
Later,
SteveO