Z-Agent Remote Control

Securely control your computer from any AI agent through an encrypted MCP tunnel.

Z-Agent Remote Control is a self-hosted system that lets any AI assistant (Claude, ChatGPT, Super Z, etc.) remotely control your Ubuntu/Linux machine through a secure, auditable MCP (Model Context Protocol) tunnel. It includes a full-featured GTK3 desktop GUI for managing the tunnel, API keys, security settings, and sending agent requests directly from your desktop.

---

Table of Contents

• Features
• Architecture
• Quick Start (5 minutes)
• Detailed Setup
• Using the Desktop App
• Connecting Your AI Agent
• Security Model
• Shell Helper
• Project Structure
• Troubleshooting
• Screenshots
• License

---

✨ Features

Desktop GUI (Z Control v5)

• 7 tabbed panels: Setup, Control, Agent, Security, Settings, Connect, Log
• One-Click Install: Downloads cloudflared, deploys MCP server, creates desktop entry, generates API key — all from the app
• MCP Server Control: Start/stop with real-time status indicators and process management
• Cloudflare Tunnel: Start/stop tunnel, displays live tunnel URL, health monitoring
• Agent Request Panel: Send commands to your own machine through the tunnel with tool selector, quick actions, response viewer, and request history
• API Key Manager: Generate, show/hide, copy, apply custom keys with strength meter
• Security Controls: Allowed directories manager, command blocklist viewer, audit log
• Settings: Port config, auto-start toggles, server info, danger zone (reset/clear)
• Connection Prompt Generator: Auto-generates a complete prompt to paste into any AI agent, updates live with current URL and key
• Share: Copy-self button to share the app with others

MCP Server

• 7 tools: run_command, read_file, write_file, list_directory, search_files, get_system_info, delete_file
• Bearer token authentication
• Path allowlist restriction (file operations only in allowed directories)
• Command blocklist (rm, sudo, shutdown, reboot, halt, mkfs, dd, chmod, chown, kill, killall, pkill)
• Comprehensive audit logging
• Zero dependencies — pure Python stdlib

Tunnel

• Cloudflare Tunnel (free, no account needed) for public HTTPS endpoint
• JSON-RPC 2.0 over HTTP POST
• Works with any AI agent that can make HTTP requests

---

🏗 Architecture

┌─────────────────┐         ┌──────────────────┐         ┌──────────────┐
│   AI Agent      │ ◄────► │  Cloudflare      │ ◄────► │  MCP Server  │
│  (Claude, Z,   │  HTTPS │  Tunnel           │  HTTP   │  (localhost)  │
│   ChatGPT...)   │  JSON- │  (cloudflared)    │  RPC    │  Port 9001    │
│                 │  RPC   │                   │         │              │
│  Sends tool     │        │  Public URL:      │         │  File I/O    │
│  calls via      │        │  *.trycloudflare  │         │  Shell exec   │
│  HTTP POST      │        │  .com             │         │  System info  │
└─────────────────┘         └──────────────────┘         └──────────────┘
                                                              ▲
                                                              │
                                                    ┌──────────────────┐
                                                    │  Z Control GUI   │
                                                    │  (GTK3 Desktop)  │
                                                    │  Manages:        │
                                                    │  - MCP Server    │
                                                    │  - Tunnel        │
                                                    │  - Keys/Security │
                                                    │  - Agent Requests│
                                                    └──────────────────┘

Data flow:

1. AI agent sends JSON-RPC POST to https://<tunnel-url>/mcp
2. Cloudflare Tunnel forwards to http://localhost:9001/mcp
3. MCP server validates Bearer token, checks security rules, executes the tool
4. Result is sent back through the same path

---

🚀 Quick Start (5 minutes)

Prerequisites

• Ubuntu/Debian Linux (or any distro with GTK3)
• Python 3.8+ with python3-gi (GTK bindings)
• Internet connection (for cloudflared download)

One Command Install

# Download and run Z Control
mkdir -p ~/.local/share/z-control
curl -sL https://raw.githubusercontent.com/YOUR_USERNAME/Z-Agent-Remote-Control/main/src/z_control.py \
  -o ~/.local/share/z-control/z_control.py
python3 ~/.local/share/z-control/z_control.py

Then inside the app:

1. Go to 🛠 Setup tab
2. Click 🚀 One-Click Install (downloads cloudflared, deploys MCP server, generates API key)
3. Click ▶ Start MCP + Tunnel
4. Go to 🔗 Connect tab → Copy the full prompt
5. Paste it into your AI agent conversation

That's it! Your AI agent can now control your computer.

---

📖 Detailed Setup

Step 1: Install System Dependencies

# Ubuntu/Debian
sudo apt update
sudo apt install -y python3 python3-gi gir1.2-gtk-3.0 cloudflared

Note: If cloudflared is not in your package repo, the Z Control app can download it automatically via the Setup tab.

Step 2: Download the Files

# Create directories
mkdir -p ~/.local/share/z-control
mkdir -p ~/.local/share/applications

# Download files
# Option A: From GitHub
wget -O ~/.local/share/z-control/z_control.py \
  https://raw.githubusercontent.com/YOUR_USERNAME/Z-Agent-Remote-Control/main/src/z_control.py
wget -O ~/mcp_server.py \
  https://raw.githubusercontent.com/YOUR_USERNAME/Z-Agent-Remote-Control/main/src/mcp_server.py

# Option B: Clone the repo
git clone https://github.com/YOUR_USERNAME/Z-Agent-Remote-Control.git
 cp Z-Agent-Remote-Control/src/z_control.py ~/.local/share/z-control/
cp Z-Agent-Remote-Control/src/mcp_server.py ~/

Step 3: Create Desktop Entry (Optional)

cat > ~/.local/share/applications/z-control.desktop << 'EOF'
[Desktop Entry]
Name=Z Control
Comment=MCP Tunnel Controller for AI Agent Remote Control
Exec=python3 ~/.local/share/z-control/z_control.py
Icon=utilities-terminal
Terminal=false
Type=Application
Categories=System;Utility;
StartupNotify=true
EOF

update-desktop-database ~/.local/share/applications/

Step 4: Launch and Configure

# Launch Z Control
python3 ~/.local/share/z-control/z_control.py

# Or find "Z Control" in GNOME Activities

Inside the app:

1. Setup tab → Click "One-Click Install" if you haven't installed cloudflared yet
2. Control tab → Start MCP Server, then Start Tunnel
3. Wait for the tunnel URL to appear (looks like https://xxx-xxx.trycloudflare.com)
4. Connect tab → Copy the connection prompt

Step 5: Connect Your AI Agent

Paste the connection prompt (from the Connect tab) into any AI agent that supports making HTTP requests. The prompt includes:

• The MCP endpoint URL
• The API key
• All available tools and their parameters
• Example JSON-RPC calls
• A ready-to-use shell helper script

---

🖥 Using the Desktop App

Tabs Overview

Tab	Purpose
🛠 Setup	One-click install, prerequisites check, share the app
⚙ Control	Start/stop MCP server & tunnel, system info, test connection, kill all
🤖 Agent	Send requests through the tunnel, quick actions, response viewer, history
🔐 Security	API key manager (generate/show/hide/copy/apply), allowed dirs, blocklist
⚙️ Settings	Port config, auto-start, server info, audit log viewer, reset
🔗 Connect	Auto-generated connection prompt with copy button
📋 Log	Real-time activity log

Agent Tab

The Agent tab lets you send commands to your own computer through the MCP tunnel — essentially a remote terminal:

1. Select a tool from the dropdown (run_command, get_system_info, etc.)
2. Type your command in the input field (e.g., ls -la /tmp)
3. Press Enter or click Send Request
4. View the response in the output panel
5. Use Quick Actions for one-click common commands (disk, RAM, processes, etc.)
6. Click any item in Request History to reload it

The agent request uses the tunnel URL if available, or falls back to localhost:{port} for local testing.

---

🔗 Connecting Your AI Agent

Option 1: Use the Connect Tab

The easiest way. Go to the 🔗 Connect tab in Z Control and click Copy Full Prompt. Paste it into your AI agent.

Option 2: Manual Connection

Your AI agent needs to send HTTP POST requests to:

POST https://<your-tunnel-url>.trycloudflare.com/mcp
Content-Type: application/json
Authorization: Bearer <your-api-key>

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"run_command","arguments":{"command":"ls -la","timeout":25}}}

Option 3: Shell Helper Script

Save this as laptop.sh and use echo 'command' | ./laptop.sh:

#!/bin/bash
MCP="https://<your-tunnel-url>.trycloudflare.com/mcp"
API_KEY='<your-api-key>'
CMD=$(cat)
PAYLOAD=$(python3 -c "import json,sys; cmd=sys.stdin.read().strip(); print(json.dumps({'jsonrpc':'2.0','id':1,'method':'tools/call','params':{'name':'run_command','arguments':{'command':cmd,'timeout':25}}}))" <<< "$CMD")
RESP=$(curl -s --connect-timeout 10 --max-time 30 -X POST "$MCP" -H 'Content-Type: application/json' -H "Authorization: Bearer $API_KEY" -d "$PAYLOAD")
echo "$RESP" | python3 -c "import sys,json; data=json.load(sys.stdin); text=data['result']['content'][0]['text']; info=json.loads(text); print(info['stdout']) if info['stdout'] else None; print('STDERR:',info['stderr'],file=sys.stderr) if info['stderr'] else None"

See src/laptop.sh.example for a ready-to-use template.

---

🛡 Security Model

Defense in Depth

Layer	Mechanism
Authentication	Bearer token (API key) required for every request
Transport	HTTPS via Cloudflare Tunnel (TLS encryption)
File Isolation	write_file, read_file, delete_file restricted to allowed directories only
Command Blocklist	Dangerous commands blocked by substring matching: rm, sudo, shutdown, reboot, halt, mkfs, dd, chmod, chown, kill, killall, pkill
Path Traversal	All paths resolved and validated against allowed directories
Audit Logging	Every tool call logged with timestamp, tool name, arguments, and result
Timeout	All commands have configurable timeout (default 25s)

Security Settings (in the GUI)

• API Key Manager: Generate strong random keys, view strength meter
• Allowed Directories: Control which directories the AI can read/write
• Command Blocklist: View all blocked commands
• Audit Log: Review all actions taken by AI agents

Important Notes

• The default API key is a placeholder — always generate a new one via the Security tab
• Tunnel URLs change every time cloudflared restarts (they're ephemeral)
• The MCP server runs on localhost only — it's never directly exposed to the internet
• File operations (write_file, read_file, delete_file) are restricted to ~/projects by default

See docs/SECURITY.md for detailed security documentation.

---

🐚 Shell Helper Script

A bash wrapper for quick command execution from your terminal:

# Make it executable
chmod +x laptop.sh

# Run commands
echo "ls -la /tmp" | ./laptop.sh
echo "df -h" | ./laptop.sh
echo "whoami" | ./laptop.sh

See src/laptop.sh.example for the template — just replace the MCP URL and API_KEY with your values.

---

📁 Project Structure

Z-Agent-Remote-Control/
├── README.md                    # This file
├── CHANGELOG.md                 # Version history
├── LICENSE                      # MIT License
├── docs/
│   ├── SETUP.md                 # Detailed setup guide
│   ├── ARCHITECTURE.md          # Technical architecture
│   └── SECURITY.md              # Security model documentation
└── src/
    ├── z_control.py             # Main GTK3 desktop GUI (Z Control v5)
    ├── mcp_server.py            # MCP server (stdlib Python, zero deps)
    └── laptop.sh.example        # Shell helper template

File Descriptions

File	Description	Dependencies
src/z_control.py	Full GTK3 desktop app with 7 tabs, embedded MCP server, one-click install	Python 3, GTK3 (python3-gi), cloudflared
src/mcp_server.py	Standalone MCP server exposing 7 tools over HTTP	Python 3 stdlib only
src/laptop.sh.example	Bash helper for terminal-based command execution	bash, curl, python3

---

🔧 Troubleshooting

MCP Server won't start

• Port in use: Another process is using port 9001. Check with lsof -i :9001 or change the port in Settings
• Python missing: Ensure python3 is installed. Z Control auto-detects this

Tunnel won't start

• cloudflared not found: Use the Setup tab's One-Click Install, or install manually:

  # Option A: apt
  sudo apt install cloudflared
  
  # Option B: Direct download
  curl -sL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o ~/.local/bin/cloudflared

• No internet: Cloudflare Tunnel requires internet connectivity

Connection test fails

• Ensure both MCP server AND tunnel are running (green health dot)
• Check that the API key matches between Z Control and your AI agent
• Tunnel URLs are ephemeral — if cloudflared restarts, you get a new URL

Z Control doesn't open from desktop

• Ensure the .desktop file points to the correct path
• Try launching manually: python3 ~/.local/share/z-control/z_control.py

GTK import errors

sudo apt install python3-gi gir1.2-gtk-3.0

~/.local/bin not in PATH

Add this to your ~/.bashrc:

export PATH="$HOME/.local/bin:$PATH"

Then source ~/.bashrc or log out/in.

---

📸 Screenshots

The app features a dark-themed GTK3 interface with 7 tabs.

Tab	Description
Setup	Prerequisites check and one-click install
Control	MCP server and tunnel management
Agent	Send requests and view responses
Security	API key and directory management
Connect	Copy connection prompt for AI agents

---

🔄 How It Works (For New Users)

1. You download z_control.py — a single Python file with everything embedded
2. Run it — python3 z_control.py — a dark-themed GUI opens
3. Click Install — downloads cloudflared, sets up MCP server, generates API key
4. Start services — one click starts both MCP server and tunnel
5. Copy the prompt — the Connect tab has a ready-made prompt for your AI agent
6. Paste into AI — your AI agent can now execute commands, read/write files, and get system info from your computer
7. Monitor everything — audit log, activity log, connection health, all in the GUI

---

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

⚠️ Disclaimer

This tool provides remote access to your computer. While security measures are in place (authentication, command blocklist, directory restrictions, audit logging), you should:

• Always use a strong, unique API key
• Review the audit log regularly
• Only enable tunnel when needed — use "Kill All & Lock Down" when done
• Keep allowed directories minimal — only grant access to what's needed
• Never share your tunnel URL and API key publicly

Use at your own risk. The authors are not responsible for any damage caused by misuse.