Quick Start

This guide walks you through deploying a complete EasyShell environment with Docker Compose. All services (Server, Web, MySQL, Redis) are fully containerized — pre-built images are automatically published to Docker Hub and GHCR via GitHub Actions.

Prerequisites

• Docker 24+ with Docker Compose v2 (included with Docker Desktop)
• Git — for cloning the repository
• At least 2 GB RAM and 10 GB disk space

Tip

No need to install Java, Node.js, or Go — all components are provided as Docker images.

Step 1: Clone the Repository

git clone https://github.com/easyshell-ai/easyshell.git
cd easyshell

Step 2: Configure Environment Variables

Copy the environment template and modify as needed:

cp .env.example .env

The defaults work out of the box. Key configuration options:

Variable	Default	Description
MYSQL_PASSWORD	18923ce29fdab04e	MySQL root password
SERVER_PORT	18080	Server API port
WEB_PORT	18880	Web frontend port
PROVISION_SERVER_URL	http://easyshell-server:18080	Agent connection URL — change to your server’s external address when deploying agents

Caution

For production, always change MYSQL_PASSWORD, JWT_SECRET, and ENCRYPTION_KEY. Never commit .env files to version control.

Step 3: Start All Services

docker compose up -d

Docker Compose will automatically pull pre-built images and start all four services:

Service	Image	Port
easyshell-server	laolupaojiao/easyshell-server:latest	18080
easyshell-web	laolupaojiao/easyshell-web:latest	18880
easyshell-mysql	mysql:8.0	13306
easyshell-redis	redis:7-alpine	16379

Tip

To use GHCR instead of Docker Hub, set in .env:

EASYSHELL_SERVER_IMAGE=ghcr.io/easyshell-ai/easyshell/easyshell-server:latest
EASYSHELL_WEB_IMAGE=ghcr.io/easyshell-ai/easyshell/easyshell-web:latest

Step 4: Verify Services

docker compose ps

All services should show healthy status within 1–2 minutes. You can also check logs for troubleshooting:

docker compose logs -f

Step 5: Login

Open http://localhost:18880 in your browser and log in with:

• Username: easyshell
• Password: easyshell@changeme

Caution

Change the default password immediately after first login.

Step 6: Deploy Agents to Managed Hosts

The EasyShell Agent runs on each server you want to manage. There are two ways to deploy:

Option A: Automatic Deployment (from Web UI)

1. Navigate to Host Management in the sidebar
2. Click Add Host → Install Agent
3. Enter the target host’s SSH credentials (IP, port, username, password/key)
4. The server will SSH into the target, upload the correct binary (amd64/arm64), and start the agent

Tip

Before using automatic deployment, make sure PROVISION_SERVER_URL in your .env is set to the server’s externally reachable address (e.g. http://your-server-ip:18080) — agents need this URL to connect back to the server.

Option B: Manual Deployment

1. Copy the pre-built binary to the target host:

scp easyshell-agent/easyshell-agent-linux-amd64 user@target:/usr/local/bin/easyshell-agent

2. Create the config file /etc/easyshell/agent.yaml on the target:

server:
  url: http://YOUR_EASYSHELL_SERVER:18080

agent:
  id: ""  # Leave empty to auto-generate from hostname

heartbeat:
  interval: 30  # seconds

metrics:
  interval: 60  # seconds

log:
  level: info

3. Start the agent:

chmod +x /usr/local/bin/easyshell-agent
/usr/local/bin/easyshell-agent --config /etc/easyshell/agent.yaml

Tip

Pre-built binaries for linux-amd64 and linux-arm64 are included in the easyshell-agent/ directory. No Go toolchain needed unless you want to build from source.

Step 7: Configure AI Assistant (Optional)

To enable the AI-powered operations assistant:

1. Navigate to System Management → AI Settings
2. Add your preferred AI model provider (e.g., OpenAI, DeepSeek, or any OpenAI-compatible API)
3. Configure the API Key and model settings
4. Test the connection

For detailed AI configuration, see the AI Configuration guide.

Developer: Build from Source

To build images locally from source instead of using pre-built images, use the development compose file:

docker compose -f docker-compose.build.yml up -d

This will build images locally using Dockerfile.server and Dockerfile.web before starting.

What’s Next?

• Core Concepts — Understand the architecture and key terminology
• Host Management — Learn how to manage hosts and clusters
• Script Execution — Run your first batch script
• AI Assistant — Use AI for intelligent operations