​

🕒 Run SimpleTool Server on your machine in minutes

1. Using Docker Compose (recommended for most users) 🐳
2. Using Docker directly (more control over container settings) 🐋
3. Running the Python code directly (better for development and customization) 🐍

​

🐳 Option 1: Docker Compose (Recommended)

• 🖥️ SimpleTool Server with FastAPI
• 🔐 SSH access
• 🖼️ Desktop environment (Xfce) accessible via built-in noVNC

docker exec -it simpletool-server supervisorctl status

​

📋 Prerequisites

• Docker 🐳
• Docker Compose 📦

​

📝 Steps

1. Clone the repository 📥
   git clone https://github.com/getsimpletool/simpletool-server.git
   cd simpletool-server/docker
   
2. Configure environment variables (optional) ⚙️ The default configuration in docker-compose.yaml works out of the box, but you can modify any of these settings:
   environment:
     - ADMIN_DEFAULT_PASSWORD=admin         # Default admin password
     - ADMIN_BEARER_HACK=abc123             # Static token for admin access
     - TOOLS_WHITELIST=                     # Tools to allow (empty = all)
     - TOOLS_BLACKLIST=                     # Tools to block
     - SSH_ENABLED=true                     # Enable SSH access
     - VNC_ENABLED=true                     # Enable VNC desktop
   
   use allready build image from ghcr.io if you dont whant to use Dockerfile:
   services:
      simpletool-server:
         image: ghcr.io/getsimpletool/simpletool-server:latest
   
3. Start the server 🏁
   docker-compose up -d
   
4. Access the server 🔗
   • 🌐 API Server: http://localhost:8000
   • 📚 Swagger UI: http://localhost:8000/docs
   • 🖥️ Web Desktop (noVNC): http://localhost:6901 (password: vncpassword)
   • 🔐 SSH: ssh -p 2222 appuser@localhost (password: appuser)

​

🛑 Stopping the server

cd docker
docker-compose down

​

🐋 Option 2: Manual Docker Setup

​

📋 Prerequisites

• Docker 🐳

​

📝 Steps

​

Method A: Pull from GitHub Container Registry (Recommended)

1. Pull the image from GHCR 📥
   docker pull ghcr.io/getsimpletool/simpletool-server:latest
   
2. Run the container 🏁
   docker run -d \
     --name simpletool-server \
     -p 8000:8000 \
     -p 2222:22 \
     -p 5901:5901 \
     -p 6901:6901 \
     -e ADMIN_DEFAULT_PASSWORD=admin \
     -e ADMIN_BEARER_HACK=abc123 \
     -e SSH_ENABLED=true \
     -e VNC_ENABLED=true \
     -v "$(pwd)/data:/app/server/data" \
     ghcr.io/getsimpletool/simpletool-server:latest
   

​

Method B: Build from Source

1. Clone the repository 📥
   git clone https://github.com/getsimpletool/simpletool-server.git
   cd simpletool-server
   
2. Build the Docker image 🔨
   docker build -t simpletool-server:local -f docker/Dockerfile .
   
3. Run the container 🏁
   docker run -d \
     --name simpletool-server \
     -p 8000:8000 \
     -p 2222:22 \
     -p 5901:5901 \
     -p 6901:6901 \
     -e ADMIN_DEFAULT_PASSWORD=admin \
     -e ADMIN_BEARER_HACK=abc123 \
     -e SSH_ENABLED=true \
     -e VNC_ENABLED=true \
     -v "$(pwd)/data:/app/server/data" \
     simpletool-server:local
   

​

🔗 Access the server

• 🌐 API Server: http://localhost:8000
• 📚 Swagger UI: http://localhost:8000/docs
• 🖥️ Web Desktop (noVNC): http://localhost:6901 (password: vncpassword)
• 🔐 SSH: ssh -p 2222 appuser@localhost (password: appuser)

​

🛑 Stopping and removing the container

docker stop simpletool-server
docker rm simpletool-server

​

🐍 Option 3: Python Direct Mode

​

📋 Prerequisites

• Python 3.10+ installed 🐍
• Git 📥

​

📝 Steps

1. Clone the repository 📥
   git clone https://github.com/getsimpletool/simpletool-server.git
   cd simpletool-server
   
2. Set up Python environment 🛠️
   # Create and activate virtual environment
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   
   # Install dependencies
   cd src/server
   pip install -r requirements.txt
   
3. Configure environment variables (optional) ⚙️ Create a .env file in the src/server directory:
   ADMIN_DEFAULT_PASSWORD=admin
   ADMIN_BEARER_HACK=abc123
   CONFIG_STORAGE_TYPE=files
   
4. Run the server 🏁
   # From the src/server directory
   python main.py
   
   Or use the convenience script:
   # From the src/server directory
   ./run_quick.sh
   
5. Access the server 🔗
   • 🌐 API Server: http://localhost:8000
   • 📚 Swagger UI: http://localhost:8000/docs

​

✅ Verifying Your Installation

1. Health check 🩺
   curl http://localhost:8000/health
   # Expected response: {"status":"ok"}
   
2. Ping test 🏓
   curl http://localhost:8000/ping
   # Expected response: {"response":"pong"}
   
3. View available tools 🔧
   curl http://localhost:8000/tools/openapi.json
   
   Probably will be empty, because we dont have any tools yet.

​

🔮 Next Steps

1. 📚 View the Swagger UI at /docs to explore API endpoints
2. 🔧 Check the available MCP tools mapped to OpenAPI standard at /tools/openapi.json (and this path you can use as tools for OpenWebUI)
3. 📡 Connect to the server via the SSE endpoint at /sse for real-time communication