SSD Nodes Learn Hosting plans →
Guides Matt ConnorBy Matt Connor

Render HyperFrames videos on a VPS

Run HyperFrames 0.8.192 on an Ubuntu VPS: Node 22, FFmpeg, Chrome libraries and fonts, a dedicated render user, preview over SSH, and the MP4 copied home.

What running HyperFrames on a VPS takes

To run HyperFrames on a VPS, the server needs Node.js 22 or newer, FFmpeg, the Chrome headless shell that HyperFrames downloads for itself, and the fonts your videos use. Once those are installed and renders have their own unprivileged user, the server turns HTML compositions into MP4 files and your laptop stays free. This guide pins hyperframes 0.8.192 on Ubuntu 24.04 or 26.04. It ends with the finished video copied back to your own machine.

HyperFrames is HeyGen's open-source framework (Apache-2.0 license) for video written as HTML. Chrome draws the composition and FFmpeg encodes the video file. A server with no GUI (graphical user interface) handles this well. The catch is that a minimal server image was not built to run a browser. A good part of this guide covers what Chrome needs that the image may not ship. If you want a model that makes video from a text prompt instead, that is a different stack, covered in running a self-hosted AI video generator.

Why this guide pins hyperframes 0.8.192

On 2026-10-24 the npm latest tag for hyperframes pointed at 0.8.192. The project ships builds very often. The GitHub release for 0.8.181 is dated 20 October, and 0.8.191 and 0.8.192 are both dated 24 October. A plain npx hyperframes asks npm for the current latest build, so the same command can run a different build next week.

Every command below names the version. Later you also pin it inside the project, so your coding agent gets the same build you tested. Before you move to a newer build, read its release notes. The 0.8.192 notes, for example, say "H265 and HDR renders work again on machines with more than 16 cores."

How big a VPS does HyperFrames need?

Start with the agent. Claude Code's documented requirements are Ubuntu 20.04 or newer, 4 GB or more of RAM (memory), an x64 or ARM64 CPU, and an internet connection. Treat 4 GB as the floor for the agent alone.

Rendering adds Chrome processes on top of that. The help text of the 0.8.192 render command says each worker is a separate Chrome process using roughly 256 MB, and the default worker count is auto. That is upstream's rough figure, not a measurement of your server. The section on timing a render shows how to measure your own box and size it from the result.

This guide covers x64 servers. On Linux ARM64, hyperframes browser ensure first looks for a system Chromium instead of downloading the headless shell, so the browser steps are different there. Check what you have:

lsb_release -ds
uname -m
free -h
df -h / /dev/shm

uname -m should print x86_64.

Which Node.js version does Ubuntu ship?

HyperFrames needs Node.js 22 or newer. The npm package declares "node": ">=22", and the CLI (command-line interface) checks the version when it starts. On an older Node it stops with this message:

HyperFrames requires Node.js >= 22 (current: <your version>). Switch Node versions and retry.

What apt gives you depends on the release. Ubuntu 26.04 ships nodejs 22.22.1, which meets the floor. Ubuntu 24.04 ships 18.19.1, which is too old. Ubuntu 22.04 ships 12.22.9. The archive gets updates, so check your own box:

apt policy nodejs

The Candidate: line is the version apt install would give you.

On Ubuntu 26.04, use the archive. Ubuntu packages npm separately from Node, so install both:

sudo apt update
sudo apt install -y nodejs npm
node --version
npm --version

On Ubuntu 24.04, use NodeSource, which lists noble as supported for Node 22. Download its setup script and read it before you run it, for example with less nodesource_setup.sh:

curl -fsSL https://deb.nodesource.com/setup_22.x -o nodesource_setup.sh
sudo -E bash nodesource_setup.sh
sudo apt install -y nodejs
node --version
npm --version

node --version should print v22. and a patch number. NodeSource's supported list did not include 26.04 when this was written. That is one more reason to use the archive there. For context, nodejs.org lists 26 as the latest LTS (long-term support) line and 22 as a supported LTS line. HyperFrames' own render image is built on Node 22.

Install FFmpeg and the libraries Chrome needs

FFmpeg does the encoding. Upstream's troubleshooting page says it is required for local video encoding. Ubuntu carries it in the universe component: 6.1.1 on 24.04 and 8.0.1 on 26.04. HyperFrames documents no minimum FFmpeg version.

unzip is easy to miss. HyperFrames needs it to extract the Chrome it downloads, and hyperframes doctor checks for it.

The shared libraries are the harder part. The headless shell is a real Chrome build. It links against graphics, printing, audio and accessibility libraries that a server image may not have. Upstream does not publish a library list for servers without Docker. It does publish its Docker images, and the list below is what those images install on Debian, translated to Ubuntu names. Four of the packages carry a t64 suffix on Ubuntu 24.04 and 26.04: libasound2t64, libgtk-3-0t64, libatk-bridge2.0-0t64 and libcups2t64. If you copy a list written for Debian or an older Ubuntu, apt stops on the old names. Look up any name it rejects with apt-cache search.

sudo apt update
sudo apt install -y ffmpeg unzip curl ca-certificates tmux jq git \
  libnss3 libgbm1 libdrm2 libxcomposite1 libxdamage1 libxrandr2 \
  libxshmfence1 libpangocairo-1.0-0 libasound2t64 libgtk-3-0t64 \
  libatk-bridge2.0-0t64 libcups2t64 fontconfig fonts-liberation \
  fonts-noto-core fonts-noto-cjk fonts-noto-color-emoji
ffmpeg -version | head -n 1

The last line should print the FFmpeg version. A headless browser for AI agents on a VPS needs the same kind of libraries, so a box that already runs one is mostly ready. You will check this list against the real Chrome binary in a moment, so a missing library cannot hide.

Why do fonts on the server differ from your laptop?

If a composition names a font the server does not have, the render will not match the preview you saw on your laptop. Upstream's Docker images install Liberation and several Noto font packages, and the command above does the same. Drop fonts-noto-cjk if your videos have no Chinese, Japanese or Korean text. If your composition uses its own font files, keep them in the project so they travel with it. Since the week of 28 September 2026, the docs say composition scripts start only after web fonts are ready, so the same composition renders the same way every time.

The package also ships a second command, hyperframes-localize-fonts. The docs site does not describe it, so this explanation comes from its 0.8.192 source. It reads HTML on standard input, embeds the font faces into that HTML, and writes the result to standard output. It takes no flags. It is set to fail closed when a font fetch fails, and it does not capture system fonts. It runs the same font step that the renderer and the preview already run, made available to other tools. It does not install fonts into the operating system, and a normal render does not need you to call it.

Create an unprivileged user for renders

HyperFrames 0.8.192 starts Chrome with --no-sandbox, --disable-setuid-sandbox and --disable-dev-shm-usage on every launch. These flags are hard-coded in its browser manager, and no render option removes them. This means Chrome's own sandbox is not protecting your server. Puppeteer's documentation says running Chrome without a sandbox is strongly discouraged, and only fit for content you trust.

That makes the Linux user that runs the render the real limit on what a hostile page can reach. Run it as root, and a page that escapes Chrome controls the whole server. Run it as a user with no sudo rights, and the page is limited by that user's permissions. Create that user and let your SSH (Secure Shell) key log in as it:

sudo useradd -m -s /bin/bash render
sudo install -d -m 700 -o render -g render /home/render/.ssh
sudo install -m 600 -o render -g render ~/.ssh/authorized_keys /home/render/.ssh/authorized_keys

From your laptop, ssh render@203.0.113.10 should log you in, and whoami should print render. Use your server's real address in place of 203.0.113.10. This home directory will also hold the Claude Code login, so read how to keep secrets out of AI agents before you put API keys in it. For a stronger boundary than a Unix user, run the whole setup in a disposable VM for coding agents.

From here on, every command runs as render unless it says otherwise.

Download the headless shell as the render user

npx --yes hyperframes@0.8.192 browser ensure
npx --yes hyperframes@0.8.192 browser path

ensure finds Chrome or downloads it. path prints only the path to the executable. Run both as render, because the cache is per user. The renderer looks in ~/.cache/hyperframes/chrome/chrome-headless-shell and then in ~/.cache/puppeteer/chrome-headless-shell, both under the home directory of whoever runs it. The render user cannot see a browser you downloaded as root.

Now check the binary against the libraries you installed:

ldd "$(npx --yes hyperframes@0.8.192 browser path)" | grep 'not found'

No output is the healthy result. A line such as libgbm.so.1 => not found names a library that Chrome cannot load, and Chrome will not start until you install it. Puppeteer's troubleshooting page uses the same ldd check. To find which package holds a missing file, run this from your admin account:

sudo apt install -y apt-file
sudo apt-file update
apt-file search libgbm.so.1

Run doctor before the first render

npx --yes hyperframes@0.8.192 doctor

The CLI reference describes doctor as the command that checks the machine for everything a render needs. It reports the CLI version, Node.js, FFmpeg, FFprobe, Chrome and Docker. The 0.8.192 source also checks CPU, memory, disk space, the archive extractor (unzip) and /dev/shm. Fix every failed check before you go on.

Two checks need context. The /dev/shm check warns when it is smaller than 256 MB. Its hint is a docker run --shm-size=512m flag, which only applies inside a container. Chrome is also started with --disable-dev-shm-usage, so treat this line as a warning to read, not a hard failure. Check the size with df -h /dev/shm. The Docker check does not matter here, because this guide renders without Docker.

For scripts, doctor --json exits 0 whenever it runs, even when a check fails. Gate on the ok field in its output instead:

npx --yes hyperframes@0.8.192 doctor --json | jq -e '.ok'

jq -e exits non-zero when ok is false, so a script can stop there.

Create the project and pin the version inside it

cd ~
npx --yes hyperframes@0.8.192 init my-video --non-interactive
cd my-video
npm install --save-exact hyperframes@0.8.192
npm ls hyperframes

init writes a hyperframes.json at the project root. Without --non-interactive it asks for a project name and an example, which you do not want inside a script. The npm install line writes the exact version into package.json and puts the CLI in node_modules/.bin. This matters because the quickstart and the agent skills call plain npx hyperframes. Inside this folder, npm finds the local copy and runs 0.8.192 instead of fetching latest. npm ls hyperframes should print hyperframes@0.8.192.

Install the HyperFrames agent skills

A skill is a folder of instructions that a coding agent loads when the task calls for it. What agent skills are and how agents load them covers the idea in full. HyperFrames publishes its own skills. The skills CLI requires Node.js 22.20 or newer, and HyperFrames' skill installer requires Git. Install them from the project folder:

cd ~/my-video
npx skills add heygen-com/hyperframes

This opens a picker with nothing selected, so choose the skills you want. npx skills add heygen-com/hyperframes --all installs all seven published skills. npx hyperframes skills update installs the core set (/hyperframes, /hyperframes-cli, /hyperframes-registry and /media-use) with no picker. By default the skills CLI installs into the current project, and its -g flag makes the install global. You want a project install here, because this folder is where the agent works.

Write the composition with Claude Code in tmux

Install Claude Code as render with the native installer:

curl -fsSL https://claude.ai/install.sh | bash

Claude Code needs a Pro, Max, Ultra, Team, Enterprise or Console account, or access through a supported third-party API provider. The free claude.ai plan does not include Claude Code. Start it inside tmux so the session survives when your SSH connection drops:

tmux new -s video
cd ~/my-video
claude

Follow the login steps it prints. Then type /hyperframes and describe the video you want: length, scenes, text, colors. Add one line to your request: "Use the hyperframes CLI installed in this folder, and do not run hyperframes@latest." Detach from tmux with Ctrl-b then d, and come back later with tmux attach -t video. Running Claude Code on a VPS with tmux covers that workflow in depth, and running a coding agent on a VPS covers the same setup for other agents.

How do you see the preview on a remote server?

Open a second tmux window with Ctrl-b then c, and start the preview server:

cd ~/my-video
npx hyperframes preview

It starts a live preview with hot reload, so the page updates while the agent edits. The default port is 3002, and in 0.8.192 the command has no --host option. The source binds the server to the IPv4 loopback address, which means only processes on the server itself can reach it. Confirm that:

ss -ltn | grep 3002

The healthy line shows 127.0.0.1:3002. If port 3002 is already in use, the server can move to another port. Read the URL the command prints, and use that port below. On your laptop, open an SSH tunnel:

ssh -N -L 3002:127.0.0.1:3002 render@203.0.113.10

Then open http://localhost:3002 in your laptop's browser. -L forwards port 3002 on your laptop to port 3002 on the server's loopback. -N tells SSH not to run a remote command, so the terminal looks idle while the tunnel is open. That is normal. Press Ctrl-c to close it. Do not open port 3002 in the firewall. The tunnel already gives you the page, and a public port would show your work to anyone who scans for it.

Render the MP4 with npx hyperframes render

Make a fast review render first, then the final one:

cd ~/my-video
npx hyperframes render --quality draft -o renders/draft.mp4
npx hyperframes render -o renders/final.mp4

The default quality is looks, at CRF 16 (constant rate factor, where a lower number means higher quality and a larger file). The docs call it the right choice for most finished work. The frame rate comes from the composition's data-fps attribute, or 30 when it has none. The root index.html renders by default. Without -o, the file goes under renders/ with the project name and a timestamp in its name. Check the result:

ffprobe -v error -show_entries format=duration -of default=nw=1 renders/final.mp4

It should print a duration= line that matches the length you asked for.

The render command also has a --docker flag, which is off by default. The rendering guide says Docker is useful for CI (continuous integration) and repeatable production environments, and is not a requirement for every final render. On a VPS where Node, FFmpeg and Chrome are already installed, you do not need it. You may see a third-party note that says rootless Docker renders need --cap-add=SYS_ADMIN. Upstream does not document that. Its troubleshooting page only covers a Docker daemon that will not start, and this guide found no option in the 0.8.192 render command for passing extra Docker arguments. Do not add kernel capabilities because of that note.

How long does a render take on your VPS?

This guide prints no render times, because only your server and your composition can answer that. Measure one render. In one tmux window, watch memory every two seconds:

free -m -s 2

In another window, time a full render:

cd ~/my-video
time npx hyperframes render -o renders/timed.mp4

The real line from time is the wall-clock time of the render. The highest value you saw in the used column of free is the highest observed sample of system-wide used or unavailable memory, calculated as total minus available. It includes other processes and can miss a peak between the two-second samples, so it does not measure the render's actual peak memory. Repeat with --workers 1 and --workers 2, and compare. More workers can finish sooner, but each one is another Chrome process.

Size the box from those numbers. Keep the highest observed system-wide usage well under total RAM, with headroom for peaks between samples; it already includes the agent session if that session is running. If a render dies partway through, check for the kernel's out-of-memory killer from your admin account with sudo dmesg | grep -i 'killed process'. A matching out-of-memory entry means a process exhausted system memory or hit a cgroup memory limit, so lower --workers and check any memory limit before moving to a bigger plan. Renders also write large temporary files, which is why doctor checks disk space. Watch df -h ~ during the timed run too.

Copy the MP4 off the server

Run this on your laptop:

scp render@203.0.113.10:my-video/renders/final.mp4 .

The remote path is relative to the render user's home directory. For large files over a weak link, rsync -avP render@203.0.113.10:my-video/renders/ ./renders/ copies the whole folder and can resume after a dropped connection. Once the files are safe on your laptop, delete old renders on the server to free disk space.

Upgrading to a newer HyperFrames build

Move to the new build on purpose, then test it before you trust it:

cd ~/my-video
npm view hyperframes dist-tags.latest
npm install --save-exact hyperframes@latest
npm ls hyperframes
npx hyperframes browser ensure
npx hyperframes doctor
npx hyperframes render --quality draft -o renders/upgrade-check.mp4

--save-exact records the exact version that latest resolved to, so the project stays pinned after the upgrade. Run browser ensure again in case the new build wants a different Chrome. npx hyperframes browser clear removes the cached download if you want to start clean. If the draft looks wrong, go back with npm install --save-exact hyperframes@0.8.192.

FAQ

Why does npx hyperframes fail on Ubuntu 24.04 with a Node.js version error?

Ubuntu 24.04's apt archive ships nodejs 18.19.1, and HyperFrames 0.8.192 requires Node.js 22 or newer. The CLI checks the version when it starts and stops with "HyperFrames requires Node.js >= 22". Install Node 22 from NodeSource with its setup_22.x script, then confirm with node --version. On Ubuntu 26.04, the archive's nodejs is already 22.22.1, so sudo apt install nodejs npm is enough.

Is it safe that HyperFrames runs Chrome with --no-sandbox?

HyperFrames 0.8.192 adds --no-sandbox itself on every Chrome launch, and no render option removes it. This means Chrome's sandbox does not protect the server. Puppeteer's documentation strongly discourages running without a sandbox for content you do not trust. Never render as root. Use a dedicated user with no sudo rights, so a page that escapes Chrome is limited by that user's permissions.

Do I need Docker to render HyperFrames videos on a VPS?

No. The --docker render flag is off by default. The HyperFrames rendering guide describes Docker as useful for CI and repeatable production environments, not a requirement for every final render. A VPS with Node.js 22, FFmpeg, the Chrome libraries and a headless shell from npx hyperframes browser ensure renders natively. Run npx hyperframes doctor to confirm the machine is ready.

Why can I not open the HyperFrames preview at my server's IP on port 3002?

In 0.8.192 the preview server listens on the loopback address 127.0.0.1, and the command has no --host option, so only the server itself can reach it. Confirm with ss -ltn | grep 3002. Open an SSH tunnel from your laptop with ssh -N -L 3002:127.0.0.1:3002 user@server, then browse to http://localhost:3002. If port 3002 was busy, use the port in the URL the preview command printed.

Why does my rendered video use different fonts than my laptop preview?

The server only has the fonts installed on it, and a minimal server image has very few. Install the fonts your composition names, for example fonts-liberation and the Noto packages that HyperFrames' own Docker images use, or keep the font files inside the project. The bundled hyperframes-localize-fonts command does not install fonts into the system. It only embeds font faces into HTML that you pass through it.

Was this article useful?

#hyperframes#video-rendering#headless-chrome#ffmpeg#ai-agents#nodejs