Daniel

Posted on Oct 1

Command Streamer: Real-Time Terminal Access for the MatrixSwarm Era

#matrixswarm #python #ai #automation

Forget SSH. You want real-time command execution, cryptographically enforced, sandboxed, and streamed straight to a custom cockpit. Welcome to TerminalStreamer.

Objective

You’re in a hardened infrastructure. No terminal access. No GUI shell. But you need live diagnostics — on-demand, observable, and safe.

So we built TerminalStreamer — a Python agent that runs shell commands on remote nodes and returns the output, live, to an operator's panel in Phoenix GUI. No open ports. No SSH. Everything rides on MatrixSwarm’s secure, signed packet fabric.

Why Not SSH?

SSH is great — until:

You can’t open a port.
You can’t allow login access.
You can’t trust shell history persistence.
You want audit, visibility, and cryptographic guardrails.

TerminalStreamer fixes that. Here’s how.

Architecture at a Glance


Phoenix (GUI)
   ⇅  (Matrix packets)
MatrixSwarm Packet Bus
   ⇅  (RSA-signed, AES-encrypted)
Matrix_Websocket
   ⇅  (self signed certs, dual SPKI verification)
TerminalStreamer (Remote Agent)

Security is First-Class

Every command is whitelisted (["uptime", "df -h", "free -m"]).
Every packet is RSA-signed + AES-sealed.
Only agents with a verified deployment certificate can speak.
You can't fake a command, and you can't intercept a reply.

Streaming Terminal in Action

When the user submits a command in the StreamViewer panel:

{
  "handler": "cmd_service_request",
  "content": {
    "service": "terminal.stream",
    "payload": {
      "session_id": "abc123",
      "token": "xyz456",
      "command": "df -h",
      "refresh_sec": 5,
      "return_handler": "terminal_panel.update"
    }
  }
}

Agent Configuration

Here’s how the declare terminal_streamer in the swarm:


{
  "universal_id": "terminal-1",
  "name": "terminal_streamer",
  "tags": {
    "packet_signing": { "in": true, "out": true }
  },
  "config": {
    "safe_shell_mode": true,
    "whitelist": ["uptime", "df -h", "free -m", "whoami"],
    "service-manager": [
      {
        "role": ["terminal.stream@cmd_stream_terminal"],
        "scope": ["parent", "any"]
      }
    ]
  }
}

This tells Phoneix template mapping to assign a pair of signing keys:

Tags: Only commands from signed packets are allowed in.

These can be accessed in the agent during runtime: self.tree_node.get('config').get('safe_shell_mode')

self.tree_node.get('config').get('whitelist')

Only whitelisted commands will be executed.
Output will be signed on the way out.

Command Execution Logic

def _is_safe_command(self, cmd: str) -> bool:
    return any(cmd.strip().startswith(w) for w in self.whitelist)

def _run_loop(...):
    if self.safe_shell_mode and not self._is_safe_command(cmd):
        output = f"[BLOCKED] Command not allowed: {cmd}"
    else:
        output = subprocess.check_output(cmd, shell=True, ...)

We don’t sandbox every command — we sandbox what you’re allowed to even send. It’s whitelist-first, not validate-after.

Signed, Sealed, Delivered

1. Wrap the command output
payload = {
  "handler": "terminal_panel.update",
  "content": {
    "session_id": ...,
    "token": ...,
    "output": output
  }
}

2. Encrypt the payload
sealed = encrypt_with_ephemeral_aes(payload, peer_pubkey)

3. Sign the outer envelope
sig = sign_data(sealed, self._signing_key_obj)

4. Send it back via MatrixSwarm relay
self.pass_packet({...}, recipient)

The receiving GUI verifies signature, decrypts the sealed blob, and routes it to the StreamViewer panel, which renders it live.

Auto-Cleanup with Broadcast Flagging

Matrix’s websocket agent emits a file-based heartbeat:


/matrix/broadcast/connected.flag.<session_id>

The terminal_streamer agent periodically checks these flags:

If the flag was touched in the last 30s → session is alive.
If not → it stops streaming and drops the thread.

No zombie loops. No leaked subprocesses. No need for the operator to remember to clean up.

Testing

We hit it with everything:

Rapid Add/Delete of favorites
Panel sync across multiple Phoenix windows
Closing sessions while streams are active
Reconnect mid-stream
Dropping bogus commands to test enforcement

It passed. No data leaks. No un-synced favorites. No stale sessions.

MatrixSwarm Integration

Unlike SSH, where everything is implicit and fragile, MatrixSwarm gives us:

Identity-driven routing (per deployment, per agent)
E2E encryption and signing (payload + metadata)
Auto-verification of sender before any command is run
Seamless rebroadcast on deployment updates (vault-wide sync)
Process lifecycle management (via heartbeats and beacon files)

You don’t build a command streamer on top of SSH. You build it on MatrixSwarm, where every packet has a name, a signature, and a role.

Bonus: Cowbell Lives!!!

And yes, we still support gameboard.py — and its most important feature:


def cowbell_clicked(self):
    self.cowbell_sound.play()
    print("[COWBELL] More Cowbell!!! 🚨🔔🐄")

Because secure infrastructure shouldn't be boring.

Final Words

This isn’t a Google-style SaaS tool.
It’s a self-cleaning, packet-signed, panel-aware, swarm-broadcast command execution engine.
Built for ops. Built to last.