unishell-q 0.5.5

Let language models run code with intelligent action system

UniShell

AI-powered natural language command execution with cloud gateway integration.

Features

• Natural Language Commands: Execute system operations using plain English
• Gateway Integration: Remote command execution through cloud gateway
• Desktop Agent Mode: Run as background agent for remote management
• Action Registry: 90+ pre-built actions for system, file, app, and network operations (including Excel, WiFi, and Docker)
• Multi-LLM Support: Works with OpenAI, Azure OpenAI, Anthropic (including Computer Use), and local models
• Safe Execution: Multi-layered safety with Policy Engine (RBAC), Path Validation, and Rollback capabilities
• Terminal Magic: Rich interactive interface with built-in commands for session management and exports
• DevOps Ready: Specialized agents for Kubernetes (AKS) and Docker management

Installation

pip install unishell-q

Quick Start

Local Interactive Mode

# Basic usage
unishell

# With Azure OpenAI
unishell --model azure/gpt-4o --api_key YOUR_KEY --api_base YOUR_ENDPOINT --api_version 2024-08-01-preview

# With OpenAI
export OPENAI_API_KEY=your-key
unishell --model gpt-4o

# Auto-run mode (skip approval)
unishell -y

Desktop Agent Mode (Gateway Integration)

Run UniShell as a background agent that executes commands from a cloud gateway:

# Start agent with gateway connection
unishell --model azure/gpt-4o --api_key YOUR_KEY --api_base YOUR_ENDPOINT --api_version 2024-08-01-preview --agent

# Configure gateway on first run
Gateway URL: http://192.168.100.227:8000
Device Token: <your-device-token>

# Agent runs in background, CLI accepts commands
> open notepad.exe
> create folder test in C:\Users\Desktop

How Agent Mode Works:

1. Agent polls gateway for pending commands
2. Executes commands locally on your desktop
3. Reports results back to gateway
4. Cloud UI shows execution status

Gateway Configuration

Agent credentials are stored in ~/.unishell/gateway_config.json:

{
  "gateway_enabled": true,
  "gateway_url": "http://192.168.100.227:8000",
  "device_token": "your-device-token"
}

To reconfigure, delete the file and restart with --agent flag.

Usage Examples

System Operations

> lock my screen
> shutdown system in 60 seconds
> get system info
> check CPU and RAM usage

File Operations

> create a file named test.txt in desktop
> copy file.txt to backup folder
> delete old_file.txt
> rename document.txt to report.txt

Application Management

> open notepad.exe
> install chrome
> force close firefox
> list installed apps

Network Operations

> ping google.com
> flush DNS cache
> check my IP address
> disconnect wifi

Python API

from unishell import unishell

# Configure LLM
unishell.llm.model = "gpt-4o"
unishell.llm.api_key = "your-key"

# Execute commands
unishell.chat("Create a Python script")

# Use gateway orchestrator
from unishell.core.gateway import ExecutionOrchestrator
from unishell.core.intent import LLMIntentClassifier, LLMParameterExtractor
from unishell.core.action_registry import DynamicActionLoader

loader = DynamicActionLoader()
registry = loader.load_all()

classifier = LLMIntentClassifier(llm_client, model_name="gpt-4o")
extractor = LLMParameterExtractor(llm_client, model_name="gpt-4o")

orchestrator = ExecutionOrchestrator(classifier, extractor, registry)
result = orchestrator.execute("open notepad", dry_run=False)

Architecture

Local Mode

User Input → Intent Classifier → Parameter Extractor → Policy Engine → Executor → Result

Gateway Mode

Cloud UI → Gateway (Redis) → Desktop Agent → Local Executor → Gateway → Cloud UI
         ↓                      ↑
    Stores Action          Polls & Reports

Command Line Options

# Model Configuration
--model, -m          Language model to use
--api_key, -ak       API key for LLM
--api_base, -ab      API base URL
--api_version, -av   API version
--temperature, -t    Model temperature

# Agent Mode
--agent, -ag         Start desktop agent mode
--gateway_url, -gu   Gateway URL for agent
--device_token, -dtoken  Device token for authentication

# Execution Options
--auto_run, -y       Automatically run generated code
--verbose, -v        Print detailed logs
--safe_mode          Enable safety mechanisms (off/ask/auto)

# Other Options
--profile, -p        Load configuration profile
--offline, -o        Disable online features
--version            Show version number

Action Registry

UniShell includes 90+ pre-built actions across categories:

• Application: open, install, uninstall, update, force_close, list
• File: create, read, write, delete, copy, move, rename, search
• Folder: create, delete, list
• System: shutdown, restart, sleep, hibernate, lock, info, resources
• Network: ping, check_ip, flush_dns, wifi_connect, wifi_disconnect
• Service: start, stop, restart, enable, disable
• Process: kill, list
• Monitoring: cpu_threshold, ram_spike, disk_full, error_logs

Actions are defined in unishell/core/action_registry/actions/.

Gateway Integration

Desktop Registration

1. Access gateway UI: http://your-gateway:8000
2. Login with credentials
3. Register desktop to get device token
4. Use token with --agent flag

Remote Command Execution

1. Submit command through gateway UI
2. Gateway queues action (PENDING)
3. Desktop agent polls and retrieves action
4. Agent executes locally (RUNNING)
5. Agent reports result (COMPLETED/FAILED)
6. UI displays result

Agent Configuration

First run prompts for configuration:

🤖 Desktop Agent Configuration
==================================================
Gateway URL: http://192.168.100.227:8000
Device Token: <paste-your-token>

Or provide via command line:

unishell --agent --gateway_url http://gateway:8000 --device_token YOUR_TOKEN

Security

• Policy Engine: Validates permissions before execution
• Dry Run Mode: Preview actions without executing
• Path Validation: Prevents directory traversal attacks
• Safe Mode: Optional code scanning and confirmation
• Device Authentication: Token-based gateway access

Troubleshooting

Agent Not Connecting

# Check gateway URL is accessible
curl http://192.168.100.227:8000/health

# Verify device token is valid
# Delete config and reconfigure
rm ~/.unishell/gateway_config.json
unishell --agent

Command Execution Fails

# Run with verbose logging
unishell --agent --verbose

# Check action exists
# View available actions in unishell/core/action_registry/actions/

Application Not Found

# Use full executable name
> open notepad.exe  # ✓ Correct
> open notepad      # ✗ May fail

# Check app is installed
> list installed apps

Development

# Clone repository
git clone <repo-url>
cd unishell

# Install in development mode
pip install -e .

# Run tests
pytest tests/

# Add new action
# Create JSON definition in unishell/core/action_registry/actions/
# Implement handler in unishell/core/execution/safe_os_adapter.py

Magic Commands

UniShell's terminal interface supports "Magic Commands" (prefixed with %) for advanced session management:

Command	Description
%% [cmd]	Run command directly in system shell
%verbose	Toggle verbose mode for detailed execution logs
%reset	Clear conversation history and reset session
%undo	Remove the last user message and its response
%save_message [path]	Export conversation to JSON file (defaults to messages.json)
%load_message [path]	Import conversation from JSON file
%tokens [prompt]	(Experimental) Calculate token usage and estimated cost
%jupyter	Export current conversation as a Jupyter Notebook (.ipynb)
%markdown [path]	Export conversation to a formatted Markdown file
%info	Display detailed system and UniShell environment information

Advanced Features

Anthropic Computer Use Integration

UniShell integrates with Anthropic's Computer Use API, allowing models like claude-3-5-sonnet to:

• Take screenshots and analyze UI elements
• Perform precise mouse clicks and keyboard inputs
• Interact with desktop applications visually
• Note: Requires --model anthropic/... and valid API key.

DevOps Agent (AKS & Docker)

The specialized devops_agent module provides deep integration for cloud-native workflows:

• AKS Management: Deploy applications, scale deployments, and manage services on Azure Kubernetes Service.
• Docker Workflow: Build, tag, and push images to registries (ACR/Docker Hub) directly from natural language.
• Auto-healing: Includes autofix actions for common configuration mismatches and deployment failures.

Deep Architecture

Policy Engine & Security

The SimplePolicyEngine implements a robust security layer:

• RBAC (Role-Based Access Control): Supports public, user, admin, and system roles.
• Environment Awareness: In production mode, UniShell automatically:
  • Blocks CRITICAL risk actions (e.g., disk.format).
  • Prevents access to system paths (C:\Windows, /etc, etc.).
  • Forces confirmation for HIGH risk actions.
• Path Validation: Real-time checking of file paths to prevent traversal and unauthorized access.

Snapshot & Rollback

For risky operations (like file.move), UniShell uses a RollbackManager:

1. Pre-execution Snapshot: Captures state (existence, path, type) before execution.
2. Commit/Rollback: If the operation fails or is cancelled, UniShell can restore the previous state.
3. Audit Trail: Every action is logged with its snapshot ID for accountability.

Action Registry Categories

UniShell includes specialized actions beyond basic OS tasks:

• Excel: excel.create, excel.update_cell, excel.save
• Networking: network.flush_dns, wifi.connect, firewall.open_port
• Monitoring: monitor.cpu_threshold, monitor.ram_spike, monitor.error_logs
• Environment: env.setup_python, env.setup_node, env.setup_virtualenv

Version

Current Version: 0.5.5

License

MIT License

Support

For issues and questions, please open an issue on GitHub.