Headless Linux and remote Studio
Studio is a local HTTP service started by muxiva; its browser does not need to run on the same
machine as the Runtime. On a headless Linux server, keep Studio on server loopback and use SSH
port forwarding to open it in Chrome, Edge, or Safari on your own computer.
flowchart LR
B["Laptop browser<br/>localhost:5678"] -->|"encrypted SSH tunnel"| S["Linux server<br/>Muxiva Studio :5678"]
B -->|"microphone WebRTC"| A["Agora Cloud"]
S -->|"C++ Bot RTC"| A
S -->|"WebSocket"| Q["Alibaba Cloud Model Studio"]The page and microphone run on your computer. Graphs, Python/C++ Nodes, logs, and .env
remain on Linux.
Recommended: SSH port forwarding
1. Start a fixed server port
For a normal project:
For the flagship voice demo in the repository:
Linux defaults to Headless Runtime, so a remote Studio requires explicit --studio --no-open.
It prints a URL like:
Keep the process running. Do not share the complete URL containing the access token.
2. Create the tunnel on your computer
Open another local terminal:
With a custom SSH port and identity file:
3. Open the complete URL locally
Paste the server's complete URL, including the fragment token, into your local browser:
Voice Room requests access to the microphone on your local computer. The browser joins Agora directly, while the C++ Bot on Linux joins the same channel with its separate UID.
Keep Studio alive after SSH disconnects
Use tmux or systemd. A minimal tmux workflow is:
Press Ctrl-b, then d to detach. Reconnect later with:
Follow logs with:
Run in a container
Listen on all interfaces inside the container, but bind the published host port to loopback:
docker run --rm \
-p 127.0.0.1:5678:5678 \
your-muxiva-image \
muxiva studio /app --host 0.0.0.0 --port 5678 --no-open
If Docker runs on your computer, replace the printed hostname with 127.0.0.1:5678 while keeping
the original #<ACCESS_TOKEN>. If Docker is remote, use the SSH tunnel above.
Not recommended: expose Studio directly
This listens on LAN or public interfaces:
Studio can edit Graphs, save Connections, and start Runtimes. Do not expose it directly to the internet. Plain remote HTTP also normally cannot obtain browser microphone permission. If remote sharing is unavoidable, place Studio behind HTTPS, authentication, a network ACL or VPN, and a firewall. Prefer SSH forwarding for individual development.
Additional Linux voice-demo requirements
- The Qwen Python Node needs no GUI and no Qwen SDK; the server must reach Model Studio's WebSocket endpoint.
- Your local browser supplies the microphone, so the Linux server needs no audio device.
- The Agora C++ Bot needs an Agora Native SDK matching the Linux architecture. The automatic macOS package cannot run on Linux; pass an extracted Linux SDK to setup:
- The server and local browser must both reach Agora. Enterprise firewalls must allow the domains and ports required by Agora.
Troubleshooting
| Symptom | Resolution |
|---|---|
Server reports an xdg-open failure |
Use run.sh --studio ... --no-open |
| Local browser refuses connection | Keep Studio and the SSH tunnel running and use the same 5678 port |
| Access token is invalid | Copy the complete URL from the current launch, including the fragment |
| Studio opens but microphone is unavailable | Use the tunneled local 127.0.0.1 URL, not remote plain HTTP |
| Browser joins but the Bot does not | Check the Linux Agora SDK, bot token, server network, and runtime log |
Next: obtain voice credentials · run the flagship voice demo.