1Shell

<div align="center"> # 1Shell **One Shell to rule them all.** **WebSSH + VPS Management Center + MCP Server + AI AgentRun.** A local priority multi-host operation and maintenance platform for humans and AI Agents. Humans can use it as a WebSSH/VPS console; AI Agents can call it through MCP, 1Shell AI, and controlled tool layers, making multiple VPSs observable, operable, auditable, and collaborative. [](https://github.com/weidu12123/1Shell/releases) [](https://nodejs.org) [](LICENSE) [](https://hub.docker.com) [Project Home](https://github.com/weidu12123/1Shell) </div> --- ## What is 1Shell? 1Shell is a multi-host operation and maintenance platform for individual developers, small teams, and lightweight operation and maintenance scenarios. It has two equally important identities: - For humans, it is a WebSSH/VPS management center for managing terminals, files, scripts, probes, audits, and AI-assisted operations. - For AI Agents, it is a MCP Server with security boundary control, encapsulating multiple VPSs into a maintainable capability layer. Traditional WebSSH panels solve the problem of "how to connect to the server"; 1Shell focuses more on the human-machine collaborative operation and maintenance closed loop after connection: ```text Human/AI Agent initiates target ↓ 1Shell AI AgentRun/MCP Server/Bridge API ↓ Host discovery -> Remote command/file/script/probe/diagnosis ↓ Harness security boundary -> execution and observation -> result verification -> audit and logging ``` In version 4.2, the core execution unit of 1Shell AI converges to **AgentRun**: a single user target corresponds to a trackable, interruptible, auditable, and verifiable running process. The old heavyweight Program/Task runtime is no longer the default product path; reusable capabilities will be gradually precipitated around successful AgentRun, Skill, Script, and lightweight AI Task. In version 4.5, the Panel and configuration are split: the configuration capability is independent of the "configuration" section, and the Panel returns to the main line of server panels such as details, hosts, files, probes, audits, etc. The next stage will start to complete the deterministic panel capabilities that 1Shell lacks, prioritizing resource discovery and read-only status from systemd, Docker/Compose, ports/processes, logs, certificates, site/reverse proxy, and host health overview. ### 1. Multi-VPS Integrated Management 1Shell provides a unified VPS workspace for managing multiple remote hosts and local environments. | Capability | Description | |---|---| | Multi-machine SSH terminal | Unified management of local Shell and remote SSH sessions | | SFTP file management | Browse, preview, edit, upload, download, create, rename, and delete remote files | | Host repository | Manage hosts, roles, tags, sorting, archiving, and connection information | | Server details | View single-machine details and cross-VPS health overview | | Service panel | Subsequent completion of systemd, Docker/Compose, ports/processes, logs, certificate status, and task-based issuance/renewal, site/reverse proxy, etc. | | Script library | Create, edit, execute, and reuse parameterized operation and maintenance scripts | | Probe monitoring | Agentless SSH probe, probe-agent, relay-agent, and traffic statistics | | Audit log | Record key commands, script execution, Bridge/MCP calls, and high-risk operations | 1Shell's goal is not to replace all professional operation and maintenance systems but to provide a complete, controllable, and easily extensible VPS operation and maintenance entry for individual developers and small teams. The Panel completion follows the "two-layer perspective": single-machine drilling provides viewing and operation capabilities close to traditional server panels; the global perspective is responsible for cross-VPS summarization, screening, comparison, and anomaly location. This is also the core product form of 1Shell that differs from single-VPS panels. ### 2. 1Shell AI and AgentRun 1Shell AI is the internal intelligent operation and maintenance Agent of the platform and the gateway for external Agents to call complex capabilities. | Concept | Description | |---|---| | AgentRun | Single target execution cycle, saving state, budget, tool strategy, trace, interrupt, and final result | | Harness | Unified boundary for AI to reach the real world, responsible for risk interception, approval, capability authorization, and audit | | Skill | On-demand loaded markdown knowledge package, guiding AI to complete specific type tasks | | Script | Reusable deterministic command template, suitable for fixed actions | | AI Task | Lightweight task object precipitated from real successful paths, still executed by 1Shell AI | The basic cycle of AgentRun is: ```text user goal -> AgentRun -> gather context -> choose a tool -> execute through Harness/policy -> observe tool result -> decide the next action -> ask user/request secret/request approval when needed -> verify outcome -> publish a truthful final status ``` The IDE Agent page provides a session sidebar, tool sidebar, timeline, approval card, structured tool card, `/compact`, and `/rewind` around this cycle. The model is still responsible for judging the next step, and the runtime is responsible for saving state, passing events, constraining tools, compressing context, and recording trajectory. ### 3. MCP Server: Operation and Maintenance Entrance for External Agents 1Shell can be exposed as a standard MCP Server to external Agents or as an internal capability bus service 1Shell AI. Claude Code, Codex, OpenCode, Hermes, and other Agents supporting MCP can use 1Shell as a server operation and maintenance tool layer. Internal and external calls go through the same capability layer: ```text Claude Code/Codex/OpenCode/1Shell AI ↓ MCP/Bridge/AgentRun ↓ Harness boundary unified control ↓ Host/file/script/probe/diagnosis/audit ``` Local access uses Bridge Token, and remote access uses Remote MCP Token. Remote MCP is disabled by default and needs to be explicitly enabled and recommended to be exposed through HTTPS. | Verification item | Description | |---|---| | Remote switch | Not explicitly enabled, not exposed to the public network | | Mandatory HTTPS | Remote mode defaults to rejecting plain text transmission | | Host/Origin whitelist | Restrict allowed access domains and browser sources | | Remote Token | Independent issuance, revocable, and settable expiration time | | Token ACL | Limit callable tools, accessible hosts, runnable scripts, and readable paths | Local MCP example: ```json { "mcpServers": { "1shell": { "url": "http://localhost:3301/mcp/sse", "headers": { "X-Bridge-Token": "replace-with-your-bridge-token" } } } } ``` Remote MCP example: ```json { "mcpServers": { "1shell": { "url": "https://your-domain/mcp/sse", "headers": { "X-Remote-Mcp-Token": "replace-with-your-remote-mcp-token" } } } } ``` ### 4. Probe System and Monitoring Closed Loop 1Shell has a built-in VPS probe system for observing server running status. | Mode | Description | Suitable scenario | |---|---|---| | Agentless SSH probe | No component installed on the target machine, collecting basic indicators through SSH | Quick access, low intrusion | | probe-agent | Install lightweight resident Agent (Go binary) on the target machine | Long-term monitoring, stable sampling, complete indicators | | probe-relay-agent | Relay Agent collects probe data from unreachable networks | Intranet, isolated network, relay scenario | Probe capabilities include CPU, memory, disk, load, process, system information, network rate, cumulative traffic, monthly traffic statistics, offline alarm, threshold alarm, Ping/DNS/HTTP diagnosis, and Agent installation, restart, uninstallation, and real status verification. ### 5. File Management and Docker Scenario Version 4.2 completes the basic write operation of the file manager: create folder, create file, rename, delete, sort, and refresh after writing. The backend provides protection for local and SFTP path, rejecting path traversal, root directory deletion, drive root directory operation, and renaming coverage. When deploying Docker, pay attention to the container perspective and host machine perspective: - Default mounting can browse the host directory in read-only mode to avoid direct modification of critical host paths by tools in the container. - If you need 1Shell to modify the host directory, change the corresponding volume from `:ro` to `:rw` and restart the container. - It is recommended to add the host machine itself as an SSH host to 1Shell, read and write through the host perspective, and the permission boundary is clearer. Access `/api/files/write-check` to verify the current file write tool chain status. ### 6. Login, 2FA, and Desktop Version Version 4.2 strengthens the basic security and release experience of remote management: - Login supports TOTP 2FA, compatible with Google Authenticator and other authenticators. - Supports one-time recovery code, which is only displayed once, and the server only saves the hash. - The settings page is independent of `/settings`, including account, security, IP access control, AI configuration, desktop version, and about page. - The desktop version supports GitHub Releases automatic update, and the browser/development mode can go to "Settings -> About" for manual download. --- ## Quick Start ### Environment Requirements - Node.js 20.18.3 recommended; Node.js 22 and 24 are supported. - Node.js 22/24 will use built-in `node:sqlite` by default, avoiding downgrade to file storage when the local `better-sqlite3` native binding is missing. - npm. - Linux/Windows/macOS can run the server. - Remote VPS needs to support SSH. - AI capabilities require OpenAI compatible API or corresponding Provider. ### Linux One-Click Installation ```bash curl -fsSL https://raw.githubusercontent.com/weidu12123/1Shell/main/install.sh | bash ``` Optional parameters: ```bash bash install.sh --port 3301 --password change-me --dir /opt/1shell bash install.sh --docker ``` ### Docker Deployment ```bash git clone https://github.com/weidu12123/1Shell.git cd 1Shell cp .env.example .env docker compose up -d ``` ### Source Code Running ```bash git clone https://github.com/weidu12123/1Shell.git cd 1Shell nvm use npm ci npm --prefix frontend ci npm --prefix frontend run build cp .env.example .env npm start ``` Windows can use: ```bat start.bat ``` Linux/macOS can use: ```bash bash start.sh ``` Default access address: `http://localhost:3301` Frontend development: ```bash npm --prefix frontend run dev ``` --- ## Initial Configuration It is recommended to complete the following configurations after startup: 1. Modify the default login account and password. 2. Confirm that `APP_SECRET` has been automatically generated by the startup script or manually configured with a strong random key for encrypting stored SSH passwords, private keys, and passphrases. 3. Configure AI Provider, such as OpenAI compatible API. 4. Add the first SSH host. 5. Enable TOTP 2FA as needed. 6. Enable Agentless probe, and deploy probe-agent if long-term monitoring is required. 7. If external Agents need to access remotely, enable remote MCP, create Remote MCP Token, and configure ACL through HTTPS exposure. Example `.env`: ```env APP_LOGIN_USERNAME=admin APP_LOGIN_PASSWORD=change-me APP_SECRET=replace-with-a-long-random-app-secret OPENAI_API_BASE=https://api.openai.com/v1 OPENAI_API_KEY=replace-with-your-key OPENAI_MODEL=gpt-4o # Leave blank will be automatically generated and saved to data/bridge-token.json BRIDGE_TOKEN= PORT=3301 ``` Please modify the default password, retain or replace with a strong random `APP_SECRET`, and access through HTTPS in the production environment. --- ## Architecture Overview ```text Browser/Desktop Shell └─ Vue 3 SPA/xterm.js/Tailwind/Pinia │ │ HTTP + WebSocket ▼ 1Shell Server ├─ Express/Socket.IO ├─ Auth/CSRF/IP Filter/Audit ├─ SSH Terminal/SFTP File Service ├─ Script Service/Script Runner ├─ Probe Service │ ├─ Agentless SSH Probe │ ├─ probe-agent │ └─ probe-relay-agent ├─ IDE Service │ ├─ session persistence/streaming events │ ├─ structured tool result normalization │ └─ /compact / /rewind ├─ AgentRun Runtime │ ├─ state/interrupt/replay/final gate │ └─ tool policy/verifier/trajectory ├─ Harness Boundary │ ├─ risk rules/approval/capability guard │ ├─ secret ref/masking │ └─ trace ├─ MCP Server ├─ Skill Registry ├─ AI Task Service ├─ AI Agent PTY（Claude Code/OpenCode/Codex） └─ SQLite/Repositories/Migrations ``` --- ## Technology Stack | Layer | Technology | |---|---| | Frontend | Vue 3, Vite, TypeScript, Tailwind CSS, Pinia, Vue Router, xterm.js | | Backend | Node.js, Express, Socket.IO | | Database | SQLite, better-sqlite3 | | SSH/SFTP | ssh2, node-pty | | AI | OpenAI compatible API, streaming output, tool call | | AI Boundary | AgentRun + Harness (unified gate, deterministic fence, capability authorization, execution trajectory) | | MCP | MCP SSE/Streamable HTTP, Remote Token ACL | | Probe | Agentless SSH, probe-agent (Go), probe-relay-agent | | Desktop | Electron, electron-builder, electron-updater | | Deployment | Docker, docker-compose, systemd, portable package | ## Project Structure ```text 1Shell/ ├── server.js # Service entry and dependency assembly ├── desktop/ # Electron desktop entry ├── frontend/ # Vue 3 frontend │ ├── src/ │ └── dist/ # Build products, not submitted in the source code repository ├── src/ │ ├── agent-runtime/ # AgentRun status, execution, playback, and final state verification │ ├── agents/ # AI CLI Agent panel and sandbox │ ├── ai/ # AI prompts and security rules │ ├── app/ # Express/Server initialization │ ├── database/ # SQLite and migrations │ ├── harness/ # AI boundary layer: dispatch/guard/capabilities/trace │ ├── ide/ # 1Shell AI dialogue engine and tool invocation │ ├── mcp/ # MCP Server │ ├── middleware/ # Security middleware │ ├── repositories/ # Data access layer │ ├── routes/ # API routes │ ├── services/ # Host, file, probe, script, audit, 2FA, and other services │ ├── skills/ # Skill registry │ └── tools/ # Unified tool layer ├── data/ │ └── skills/ # Built-in Skill and template; running database not submitted ├── agent/ # probe-agent/relay-agent (Go) ├── scripts/ # Build, packaging, and testing auxiliary scripts ├── .github/workflows/ # CI and release workflow ├── Dockerfile ├── docker-compose.yml └── install.sh ``` --- ## Security Design 1Shell faces real server operation scenarios, and security boundaries are one of the core designs. Security measures are divided into two layers: external security and AI manipulation security. ### External Security | Mechanism | Description | |---|---| | Login Authentication | Username and password + Session management, failure lockout to prevent brute-force cracking, and timing security comparison | | 2FA | TOTP two-step verification, supporting one-time recovery code | | CSRF Protection | Session Cookie + CSRF Token | | IP Access Control | Whitelist/blacklist dual-mode, supporting CIDR, and hot update without restart | | Credential Encryption | SSH password, private key, and Passphrase are encrypted and stored using AES-256-GCM | | Bridge/MCP Authentication | Bridge Token and Web Session isolation; Remote Token supports ACL, revocation, and expiration | ### AI Manipulation Security AI execution commands, file read/write, Agent installation, script invocation, and other real-world operations must go through Harness. | Mechanism | Description | |---|---| | Unique Boundary | AI reaching the external world uniformly through Harness dispatch | | Risk Rules | Disaster commands, obvious danger writes, and unauthorized tools are intercepted before execution | | Capability Minimum Authorization | AgentRun/Task/MCP Token can limit tool, host, path, and script scope | | Human Review Downgrade | Write operations and high-risk operations can enter manual approval | | Secret Reference | AgentRun trace does not save key plaintext, only refills secret ref | | Output Desensitization | Tokens, passwords, private keys, and other sensitive information are encoded before logging and frontend output | | Execution Trajectory | Tool invocation, observation, interception reasons, and final status can be traced | The design goal of 1Shell is not to let intelligent agents bypass the operation and maintenance security boundary but to participate in operation and maintenance processes under clear authorization, auditable, and verifiable conditions. --- ## Applicable Scenarios - Personal developers manage multiple VPS. - Small teams uniformly manage test machines, deployment machines, and service nodes. - Handle terminals, files, scripts, and monitoring in the browser simultaneously. - Let intelligent agents assist in troubleshooting, inspection, deployment, and maintenance within authorized scope. - Open 1Shell to external Agent collaboration through MCP, such as Claude Code, Codex, and OpenCode. - Build a personal operation and maintenance hub locally, prioritizing controllability and auditability. --- ## Development and Verification ```bash nvm use npm ci npm test npm --prefix frontend ci npm --prefix frontend run typecheck npm --prefix frontend run build ``` Probe Agent: ```bash cd agent go test ./... ``` --- ## License [MIT](LICENSE) 2025 weidu12123 ## Friendly Links http://linux.do