Terminal Streamer: Please Hold While We Ask the Server What’s Wrong

Thank you for calling the Production Incident Hotline.

Press 1 if someone thinks it is DNS.

Press 2 if the dashboard is green but the customers are red.

Press 3 if you would like to ask the actual server a question before scheduling a cross-functional guessing session.

We are pressing 3.

MatrixSwarm’s terminal_streamer agent runs Linux commands on the swarm host and returns their output to the Terminal panel in Phoenix. Run a command once, or repeat a short diagnostic at a chosen interval. The palette supplies a command whitelist, and the panel can show you what the running agent has configured.

It is a handy way to answer “How full is the disk?” while everyone else is still establishing the incident’s preferred emoji.

Get the host ready, then assemble a small swarm

If MatrixOS is not installed, add and test the target server’s SSH connection in Phoenix’s Registry, including its trusted host fingerprint. Open Railgun → Install MatrixOS…, select the target, and choose Local Full Install with your MatrixOS source folder or Install from GitHub. For a fresh setup, select Create new venv, click Install MatrixOS, and check the completion result. Installation requires root or passwordless sudo access on the target.

Already installed? Excellent. We have successfully avoided reinstalling the building to use the telephone.

Open Deploy → Swarm Workspaces and choose New, or Open an existing workspace. Keep the matrix root and add the following agents beneath it from the Agent Palette:

Agent	Responsibility
terminal_streamer	Runs commands and returns their results
matrix_https	Ingress for Phoenix commands over HTTPS
matrix_websocket	Egress for replies back to Phoenix
log_streamer	Makes the agents’ own logs available in the cockpit

The HTTP ingress is named matrix_https in the current palette. Resolve the required packet-signing assignments and the HTTPS/WSS connection and certificate requirements. Set addresses and ports that Phoenix can reach. Keep the supplied service roles for this first walkthrough.

Five agents including Matrix. Enough staff to answer the phone without forming a steering committee.

Two kinds of output, two different jobs

Terminal command results and agent logs take different paths through the application:

• Terminal output: terminal_streamer executes the requested command and sends the result through the reply route to the Terminal panel.
• Agent Logs: log_streamer reads the selected agent’s log and sends it back for operational diagnosis.

Both use the configured return transport in this swarm, provided by matrix_websocket. You do not need log_streamer to carry command stdout. We include it so you can inspect the agents when troubleshooting the command and reply path.

The WebSocket relay advertises hive.rpc, which the terminal agent uses for replies. The terminal agent’s service roles cover starting a run, stopping repeats, and listing allowed commands. You can keep those details at their supplied defaults and get on with the job.

The command menu is already written

Yes, the commands are whitelisted. The current palette sets safe_shell_mode to true and supplies this list:

Command	The question it helps answer
whoami	Which account is actually running this?
uptime	How long has the host been up, and what does its load look like?
df -h	How much filesystem space is available?
free -m	What does memory usage look like in MiB?
top -b -n 1 -c	Can I get one batch-mode process snapshot?
ps -eo pid,user,%cpu,%mem,etime,cmd --sort=-%cpu	Which processes deserve a closer look?

For the first deployment, use that supplied configuration. List Allowed asks the running agent for its configured list; that is more useful than assuming every old workspace has the newest palette values.

Commands run with the terminal agent’s OS permissions on the remote host. The account you use to install MatrixOS and the account running the swarm are separate concerns. whoami is an excellent first call because Linux rarely accepts “but I thought I was root” as supporting documentation.

There is one important boundary: the current filter checks command prefixes, and execution uses a shell. Treat this as a facility for trusted operators, not a security sandbox or exact-command isolation. Keep safe shell mode enabled, use the intended diagnostic commands, and run the swarm with appropriately limited permissions. The word “safe” in a setting does not negotiate with the kernel on your behalf.

Launch through Railgun

Click Deploy inside the workspace. Supply a deployment label, choose the Registry SSH target, set a universe name and runtime Linux user, review the resolved directive, and complete the launch flow. Use a distinct demo universe for the first exercise, and verify Railgun’s remote result.

Phoenix prepares the encrypted runtime directive and keeps the deployment record in its encrypted vault. Railgun verifies the SSH host, prepares the runtime account and applicable grants, and sends the sealed boot envelope to MatrixD over SSH stdin. MatrixD decrypts it in memory and starts the swarm, without leaving loose directive/key boot files behind.

Then select the deployment and click Connect. Deployment launches the swarm; Connect opens its cockpit. The hold music is optional.

Your first call: identify the caller

Select terminal_streamer in the live agent tree and open its Terminal specialty panel.

1. Click List Allowed and read the returned command list.
2. Enter whoami in the command field.
3. Set the adjacent refresh field to 0 for one execution.
4. Click Run and confirm the returned account name.
5. Repeat with uptime or df -h, keeping refresh at 0 while you check the basics.

These results come from the machine running the agent. Phoenix is the console you are using to ask the question; your workstation’s disk is not secretly auditioning for the server’s role.

With the stock list, a benign command such as hostname is outside the supplied prefixes and should return a [BLOCKED] Command not allowed message. That is a useful functional check of the configured filter, not proof of a hardened sandbox.

Put one useful question on repeat

Try free -m with a refresh value of 5 and click Run. The agent executes the command, returns the completed result, waits five seconds, and runs it again.

That timing matters: execution time plus the refresh delay determines the next run. It is not a promise of samples exactly five seconds apart.

A refresh value of 0 runs once. Use positive whole seconds for repeats. The panel’s Auto-Refresh display control is separate from this execution interval; toggling how output is displayed does not replace the refresh field or stop the remote loop.

Click Stop when you have enough samples. Starting a new run in the same cockpit session replaces that session’s previous repeat schedule.

A useful favorite might be df -h with a modest refresh interval. Enter the command and interval, then choose Add to Favorites. Double-clicking a favorite populates the fields; click Run to execute it. Saving a favorite does not add a command to the agent’s whitelist.

Your own little diagnostic menu. Finally, a menu where pressing 2 does something.

What “streaming” means here

The implementation collects a command’s output before sending the result. It uses Python’s subprocess.check_output, then broadcasts the completed output through the swarm’s reply machinery. Repeated snapshots make the panel useful for observing changes over time.

This is not a persistent interactive terminal session. There is no PTY keyboard conversation with vim, no interactive password prompt, and no lasting shell state between separate runs. A working-directory change in one invocation is not carried into the next.

Choose commands that finish and produce manageable output. That is why the supplied top command uses batch mode and a single iteration. A never-ending command can keep the result waiting indefinitely; this execution path does not set a command timeout.

Stop cancels future repetitions; it does not terminate a subprocess already running. The current invocation may still finish and return output. If it is stuck, use your normal authorized host-management path to inspect it. Repeatedly clicking Run is not a medically recognized treatment for impatience.

If the line goes quiet

Start with what you can observe:

Symptom	First check
List Allowed produces no reply	Connection, signing assignments, service discovery, and the WebSocket return route
Command returns [BLOCKED]	The running agent’s allowed list and the command you entered
Command returns [ERROR]	Command availability and permissions on the swarm host
A command appears to hang	Whether it finishes without input and returns bounded output
Terminal results work, but Agent Logs are empty	The separate log_streamer agent and its route

The terminal agent also monitors relay session freshness and can remove stale repeat sessions. Keep this first example to one WebSocket reply relay, and use Stop intentionally when your observation is complete. A disconnected panel is not a durable job scheduler.

Use the agents’ own logs for the remaining clues. A command failure may be presented as an error summary rather than every detail you would see in a normal terminal, so keep your usual host-level diagnostic tools available too.

You now have the same repeatable habit as the other small swarms: install the runtime once, build or edit the workspace, resolve its requirements, deploy through Railgun, connect, and verify a useful result.

This time the useful result is the server answering for itself.

Thank you for calling the Production Incident Hotline. Your next incident may still involve DNS, but at least we have asked the disk.

Victory Always. Please stop the refresh loop before leaving the call.

---

🌐 Links & Resources:

Try MatrixSwarm: https://matrixswarm.com

Join the Community / Discord: https://discord.gg/2USbWVBVV

Download Server: https://github.com/matrixswarm/matrixswarm

Youtube: https://www.youtube.com/channel/UCMjiY4_-W2KP5fHXO0eC2ug