FAQ
General
Section titled “General”What is EasyShell?
Section titled “What is EasyShell?”EasyShell is a lightweight server management and intelligent operations platform. It provides a centralized web interface for managing multiple Linux servers, executing scripts across hosts, and leveraging AI for automated operations.
Is EasyShell free?
Section titled “Is EasyShell free?”Yes. EasyShell is open-source software released under the MIT License. You can use it freely for personal and commercial purposes.
What operating systems does the agent support?
Section titled “What operating systems does the agent support?”The EasyShell agent is a single Go binary that runs on:
- Linux — amd64, arm64 (primary target)
- macOS — amd64, arm64 (for development/testing)
Windows is not currently supported for the agent.
What are the minimum server requirements?
Section titled “What are the minimum server requirements?”| Component | Minimum | Recommended |
|---|---|---|
| Server | 2 CPU, 4GB RAM, 20GB disk | 4 CPU, 8GB RAM, 50GB disk |
| Agent | 1 CPU, 128MB RAM, 50MB disk | 1 CPU, 256MB RAM, 100MB disk |
| MySQL | 8.0+ | 8.0+ |
| Redis | 7.0+ | 7.0+ |
Installation
Section titled “Installation”How do I install EasyShell?
Section titled “How do I install EasyShell?”The fastest way is Docker Compose:
git clone https://github.com/easyshell-ai/easyshell.gitcd easyshelldocker compose up -dcd easyshell-server && ./gradlew bootRuncd easyshell-web && npm install && npm run devSee the Docker installation guide for detailed instructions.
The server fails to start with a database connection error
Section titled “The server fails to start with a database connection error”Verify MySQL is running and accessible:
docker compose psdocker compose logs mysqlCommon causes:
- MySQL hasn’t finished initializing (wait 30 seconds after
docker compose up) - Port 3306 is occupied by another MySQL instance
docker-compose.ymlcredentials don’t matchapplication.yml
The web frontend shows a blank page
Section titled “The web frontend shows a blank page”- Check the browser console for errors (F12 → Console)
- Verify the server is running on port 18080
- Check that CORS is configured to allow
http://localhost:5173 - Clear browser cache and reload
How do I deploy the agent to a remote host?
Section titled “How do I deploy the agent to a remote host?”# Copy the agent binaryscp easyshell-agent-linux-amd64 user@remote:/usr/local/bin/easyshell-agent
# SSH into the host and start the agentssh user@remotechmod +x /usr/local/bin/easyshell-agenteasyshell-agent --server http://YOUR_SERVER_IP:18080See the Agent deployment guide for systemd service setup.
The agent shows “connection refused”
Section titled “The agent shows “connection refused””- Verify the server is reachable from the agent host:
curl http://SERVER_IP:18080/api/health - Check firewall rules — port 18080 must be open
- Ensure the server URL in the agent config is correct (use IP, not
localhost)
How often does the agent report metrics?
Section titled “How often does the agent report metrics?”By default:
- Heartbeat: every 30 seconds
- Metrics: every 60 seconds
These intervals are configurable in the server settings. See Server Configuration.
Script Execution
Section titled “Script Execution”Can I execute scripts on multiple hosts simultaneously?
Section titled “Can I execute scripts on multiple hosts simultaneously?”Yes. Select multiple hosts or an entire cluster, then execute a script. EasyShell supports three execution strategies:
- Parallel — All hosts at once
- Sequential — One at a time, stops on failure
- Rolling — Batch execution with configurable batch size
What happens if a script times out?
Section titled “What happens if a script times out?”The agent kills the script process after the configured timeout (default: 5 minutes). The execution is marked as TIMEOUT in the history. You can adjust the timeout per-script or globally in the server configuration.
Can I use script parameters?
Section titled “Can I use script parameters?”Yes. Define parameters in your script using environment variables, then pass values when executing:
#!/bin/bashecho "Checking disk usage threshold: ${THRESHOLD:-80}%"df -h | awk -v threshold="$THRESHOLD" '{if(NR>1 && $5+0 > threshold) print $0}'AI Features
Section titled “AI Features”Do I need an OpenAI API key?
Section titled “Do I need an OpenAI API key?”AI features are optional. EasyShell works fully without AI. If you want to use the AI assistant, scheduled inspections, or SOP automation, you need an API key from any OpenAI-compatible provider.
See AI Configuration for supported providers.
Can I use a local LLM instead of OpenAI?
Section titled “Can I use a local LLM instead of OpenAI?”Yes. EasyShell supports any OpenAI-compatible API. You can use:
- Ollama — Local LLM with
base-url: http://localhost:11434/v1 - vLLM — High-performance inference server
- LocalAI — Drop-in OpenAI replacement
Is my data sent to external AI services?
Section titled “Is my data sent to external AI services?”Only when you actively use AI features (chat, inspections). The data sent includes:
- Your chat messages
- Host system information (for inspections)
- Script content (when asking AI to analyze scripts)
No data is sent if AI features are disabled.
Security
Section titled “Security”Is it safe to expose EasyShell to the internet?
Section titled “Is it safe to expose EasyShell to the internet?”We recommend placing EasyShell behind a reverse proxy (Nginx/Caddy) with:
- HTTPS enabled
- Strong authentication
- Rate limiting
- IP allowlisting if possible
See the Security configuration guide for a complete checklist.
How are agent credentials stored?
Section titled “How are agent credentials stored?”Agent tokens are stored in the server database (MySQL). On the agent side, the token is stored in a local configuration file. We recommend:
- Setting file permissions to
600on the agent config - Using TLS for all agent-server communication