Shinrai

AI-Powered SSH Management Agent

Shinrai is an intelligent terminal-based SSH management tool that combines AI capabilities with secure server administration. Interact with your remote servers using natural language, while Shinrai handles command generation, execution, and safety validation.

┌────────────────────────────────────────────────────────┐
│ ██████████    ███████╗██╗  ██╗██╗███╗   ██╗            │
│ ██ ▫▫ ▫▫ ██   ██╔════╝██║  ██║██║████╗  ██║            │
│ ██████████    ███████╗███████║██║██╔██╗ ██║            │
│  ██ ██ ██     ╚════██║██╔══██║██║██║╚██╗██║            │
│  ██ ██ ██     ███████║██║  ██║██║██║ ╚████║            │
│   █    █      ╚══════╝╚═╝  ╚═╝╚═╝╚═╝  ╚═══╝            │
│                信頼  AI SSH MANAGEMENT                 │
└────────────────────────────────────────────────────────┘

Demo

https://github.com/tegal1337/SHINRAI/assets/action.mp4

Watch Shinrai in action: natural language server management with AI-powered command generation and real-time execution.

Why "Shinrai"?

Shinrai (信頼) is the Japanese word for "trust" or "reliability" - two fundamental pillars of SSH server management. The name embodies:

• Trust: Confidence in AI-driven command execution with built-in safety mechanisms
• Reliability: Consistent, secure server operations
• Japanese Philosophy: Minimalist design inspired by Zen principles of simplicity and precision

The name reflects the project's core mission: creating a trustworthy AI agent that users can rely on for critical infrastructure management.

Features

Core Capabilities

• Natural Language Interface: Communicate with servers using plain English
• Multi-Server Management: Store and switch between multiple SSH configurations
• Flexible Authentication: Support for both password and SSH key authentication
• AI-Powered Command Generation: Leverages OpenRouter models (Claude, GPT-4, Gemini, etc.)
• Safety-First Approach: Automatic detection and confirmation of dangerous operations
• Real-Time Streaming: Live command output display with minimal latency
• Conversation History: Context-aware interactions with command history
• Model Selection: Choose from 100+ AI models via OpenRouter integration

Safety System

Shinrai implements comprehensive safety checks for dangerous operations:

• Recursive deletions (rm -rf, rm -r)
• Disk operations (dd, mkfs, fdisk)
• System state changes (shutdown, reboot, halt)
• Permission modifications on system directories (chmod 777, chown)
• Potential malicious patterns (fork bombs, disk writes)

All flagged commands require explicit user confirmation before execution.

Installation

Prerequisites

• Node.js 18 or higher
• npm or yarn package manager
• SSH access to target servers
• OpenRouter API key (Get one here)

Global Installation (Recommended)

Install Shinrai globally via npm:

npm install -g shinrai

Then run anywhere:

shinrai

Local Installation

1. Clone the repository:

git clone https://github.com/tegal1337/SHINRAI.git
cd SHINRAI

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Run Shinrai:

npm run dev

Development Mode

For local development with hot reload:

npm run dev

Configuration

Initial Setup

On first launch, Shinrai will guide you through:

1. OpenRouter API Key: Enter your API key for AI model access
2. SSH Server Configuration:
   • Server name (friendly identifier)
   • Host address
   • Port (default: 22)
   • Username
   • Authentication method (password or private key)

Adding Multiple Servers

Access the settings menu ([S] key) to:

• Add new SSH servers
• Select different AI models
• Manage existing configurations

Model Selection

Shinrai supports popular models including:

• Anthropic Claude (Sonnet 4, Opus 4)
• OpenAI GPT (4o, 4o-mini)
• Google Gemini (2.0 Flash, Pro 1.5)
• Meta Llama (3.1 70B)
• DeepSeek Chat

Usage

Basic Commands

# Natural language queries
"Show disk usage"
"List running processes"
"Check memory usage"
"Find large files in /var/log"

# Built-in commands
/clear      - Clear conversation history
/help       - Show help menu
/settings   - Open settings menu
/servers    - Switch to server selector
/exit       - Exit application

Navigation

• Arrow Keys: Navigate history and menus
• Enter: Execute/confirm selection
• Escape: Return to previous screen
• Ctrl+C: Force quit

Example Workflow

1. Launch Shinrai and select a server
2. Type: "What's using the most disk space?"
3. Shinrai generates and executes: du -sh /* | sort -rh | head -10
4. Review output and AI analysis
5. Continue conversation: "Delete old log files in /var/log"
6. Confirm dangerous operation when prompted

Architecture

User Input → AI Agent → Safety Validator → SSH Client → Server
     ↑                                                      ↓
     └──────────── AI Analysis ← Command Output ───────────┘

Project Structure

src/
├── components/          # React Ink UI components
│   ├── Header.tsx      # Branding and status display
│   ├── ServerSelector.tsx
│   ├── ModelSelector.tsx
│   ├── ChatWindow.tsx
│   ├── InputBar.tsx
│   └── ...
├── agent.ts            # AI interaction logic
├── ssh-client.ts       # SSH connection handling
├── safety.ts           # Command safety validation
├── credentials.ts      # Credential management
├── types.ts            # TypeScript interfaces
└── index.tsx           # Application entry point

Development

Scripts

npm run dev      # Run in development mode
npm run build    # Compile TypeScript
npm start        # Run compiled version

Technology Stack

• Runtime: Node.js
• Language: TypeScript
• UI Framework: React with Ink (terminal rendering)
• SSH Library: ssh2
• AI Provider: OpenRouter SDK
• State Management: React hooks

Security Considerations

1. Credential Storage: Stored locally in ~/.shinrai/credentials.json
2. API Keys: Never committed to version control
3. Command Validation: All destructive operations require confirmation
4. SSH Best Practices: Support for key-based authentication
5. No Remote Logging: All operations remain local

Changelog

Version 1.0.0 (2026-01-13)

Added

• Initial release with core SSH management features
• Natural language command interface powered by AI
• Multi-server configuration support
• Password and SSH key authentication
• Interactive model selection from OpenRouter catalog
• Real-time command output streaming
• Comprehensive safety validation system
• Command history navigation
• Setup wizard for first-time users
• Settings menu for configuration management

Security

• Implemented dangerous command detection
• Added user confirmation for destructive operations
• Secure local credential storage

UI

• Terminal-based interface with Ink framework
• Clean box-drawing ASCII art design
• Smooth borders and consistent styling
• Color-coded status indicators
• Responsive layout with fixed-width components

Contributing

Contributions are welcome. Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/improvement)
3. Commit changes with clear messages
4. Push to your fork
5. Submit a pull request

License

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

Acknowledgments

• OpenRouter for AI model access
• Anthropic, OpenAI, Google, Meta for language models
• The open-source community for excellent libraries

Support

For issues, questions, or feature requests:

• GitHub Issues: https://github.com/tegal1337/SHINRAI/issues
• Documentation: https://github.com/tegal1337/SHINRAI/wiki

Built with trust. Powered by AI.