bitHuman docs
Status Get an API secret
Get startedPlatformsDeployModelsBuildAPIPerformance
Downloads & versionsChangelogPricing and creditsTroubleshootingFAQGlossarySupport & communityFor AI agentsStatus
Get an API secret →

Kiosk on a Linux PC

More ▾
View as markdown Open in Claude ↗ Open in ChatGPT ↗

A live avatar full screen on a standard Linux PC with no GPU: the CLI renders it on the CPU, Chrome shows it in kiosk mode, and visitors talk to it.

20 min Creator plan or higher No GPU Your servers Linux x86_64 / arm64 API secret CLI 2.8.3

What you’ll build

A screen that greets visitors with a live avatar that listens and answers. The avatar renders on the PC’s CPU, so a standard Linux PC with no GPU is enough.

You need:

  • a Linux PC (x86_64 or arm64) with a screen, speakers and a microphone;
  • Google Chrome;
  • an API secret on the Creator plan or higher.
The kwame-warm-museum-guide avatar answering a visitor, full screen in Chrome on a Linux PC, from bithuman runPlay with sound (17 seconds, captions)
Captured on a Linux PC, Intel Core i7-13700F (Ubuntu 24.04) · CLI 2.8.2 (bithuman run) · kwame-warm-museum-guide (Essence 2) · 2026-09-27. Rendered on the CPU alone: the PC's graphics card was hidden from the process. The visitor's question is the microphone input, mixed into the recording.

Steps

6 steps

  1. Install the CLI

    curl -fsSL https://install.bithuman.ai | sh
sudo apt install -y ffmpeg python3-venv     # Ubuntu/Debian

    The Linux download includes livekit-server, which bithuman run starts for you.

    Expected

    bithuman --version prints the CLI and engine versions.

  2. Give the kiosk its own API secret

    Create a secret for this kiosk alone, so you can revoke it without touching anything else (API secrets). Put it in the kiosk’s environment:

    export BITHUMAN_API_SECRET="<this kiosk's API secret>"
    Expected

    bithuman account shows your plan and credit balance.

  3. Download the avatar

    Download it once, ahead of the first visitor. bithuman pull prints the file’s path:

    AVATAR=$(bithuman pull kwame-warm-museum-guide)    # or your own agent code
echo "$AVATAR"

    A file always renders on this machine. Any Essence 2 or Expression 2 avatar works on the CPU.

    Expected

    A path ending in kwame-warm-museum-guide.imx. The next runs reuse it.

  4. Start the avatar

    bithuman run "$AVATAR"

    The first run also installs the conversation brain (about 350 MB). By default the conversation runs on bitHuman’s voice chat; set OPENAI_API_KEY to use your own OpenAI account, or BITHUMAN_LOCAL=1 for the local conversation brain.

    Expected

    The CLI prints the page's URL, such as http://127.0.0.1:8088/KWAMEWARMMUSEUMGUIDE. Open it in a browser, press the start button and allow the microphone: the avatar answers when you speak.

  5. Show it full screen

    Open the URL in Chrome’s kiosk mode, with a profile of its own so the microphone permission is remembered:

    google-chrome --kiosk --user-data-dir="$HOME/.kiosk-chrome" "http://127.0.0.1:8088/KWAMEWARMMUSEUMGUIDE"
    Expected

    The avatar fills the screen with no browser chrome. The first time, allow the microphone once; Alt+F4 leaves kiosk mode.

  6. Choose online or fully offline

    A session checks your API secret when it starts and keeps rendering through a network drop of up to 5 minutes, so this kiosk needs the network to start a conversation.

    For a site with no internet at all: Offline license is only available to Business and Enterprise clients who want to run realtime avatars completely locally, off the internet — e.g. kiosks, trade shows, ATM machines, embedded screens. Linux PCs and terminals; arranged through sales. See Fully offline.

    Expected

    Online, the kiosk is ready: it needs the network each time a session starts. For fully offline, talk to sales before you deploy.

How it works

A LINUX PC · CPU ONLY, NO GPUYour appthe CLI, the Python SDK or the LiveKit pluginThe avatar renders on the CPUits audio and video stay on this PCThe conversationthe local brain, your own services, orbitHuman'sBITHUMANCredential check and usageusage: noaudio, video ortextthe avatar,once
CPU only (no GPU). On a standard Linux PC with no GPU, both models render live on the CPU, and the avatar's audio and video stay on the PC. The conversation runs where you choose: the CLI's local conversation brain, your own services, or bitHuman's. For the rendering, bitHuman receives a credential check, the avatar download and usage reports with no audio, video, images or conversation text.

bithuman run starts a local livekit-server, the conversation brain and the avatar on this PC. Chrome joins as the visitor: it sends the microphone and shows the avatar’s video, all on 127.0.0.1. The page is served on the loopback address only; --host 0.0.0.0 (with BITHUMAN_ALLOW_PUBLIC_BIND=1) opens it to the network.

Make it your own

  • Your avatar: create one from a portrait (Create your own avatar), then bithuman pull <agent code>.
  • Its persona and voice: Persona and Voices.
  • Start at boot: run bithuman run "$AVATAR" from a service with BITHUMAN_API_SECRET in its environment, and start the kiosk browser from the desktop session’s autostart.
  • What it costs: active session time, talking or idle, billed to the second at the rates on Pricing. The conversation’s rate depends on the brain you choose.
  • Speed on your PC: the CPU-only rows on Performance are measured on a standard desktop CPU.

Troubleshooting

SymptomFix
bithuman exits with code 77No API secret: export BITHUMAN_API_SECRET, or run bithuman login once.
livekit-server is not foundInstall again with the one-line installer; the Linux download includes it.
The avatar does not answerRun bithuman doctor: it names the missing part (credential, brain, ffmpeg).
Chrome asks for the microphone every timeKeep the same --user-data-dir; the permission is stored in that profile.
No sound in kiosk modeChoose the speaker as the default output in the system’s sound settings, then reload the page.
The picture stuttersClose other heavy programs; see the CPU-only rows on Performance for the reference machine.