GUI Server

Launch the full OpenHands web GUI using Docker

Overview

The openhands serve command launches the full OpenHands GUI server using Docker. This provides the same rich web interface as OpenHands Cloud, but running locally on your machine.

openhands serve

This requires Docker to be installed and running on your system.

Prerequisites

• Docker installed and running
• Sufficient disk space for Docker images (~2GB)

Basic Usage

# Launch the GUI server
openhands serve

# The server will be available at http://localhost:3000

The command will:

1. Check Docker requirements
2. Pull the required Docker images
3. Start the OpenHands GUI server
4. Display the URL to access the interface

Options

Option	Description
--mount-cwd	Mount the current working directory into the container
--gpu	Enable GPU support via nvidia-docker

Mounting Your Workspace

To give OpenHands access to your local files:

# Mount current directory
openhands serve --mount-cwd

This mounts your current directory to /workspace in the container, allowing the agent to read and modify your files.

Navigate to your project directory before running openhands serve --mount-cwd to give OpenHands access to your project files.

GPU Support

For tasks that benefit from GPU acceleration:

openhands serve --gpu

This requires:

• NVIDIA GPU
• NVIDIA Container Toolkit installed
• Docker configured for GPU support

Examples

# Basic GUI server
openhands serve

# Mount current project and enable GPU
cd /path/to/your/project
openhands serve --mount-cwd --gpu

How It Works

The openhands serve command:

1. Pulls Docker images: Downloads the OpenHands runtime and application images
2. Starts containers: Runs the OpenHands server in a Docker container
3. Exposes port 3000: Makes the web interface available at http://localhost:3000
4. Shares settings: Uses your ~/.openhands directory for configuration

Stopping the Server

Press Ctrl+C in the terminal where you started the server to stop it gracefully.

Comparison: GUI Server vs Web Interface

Feature	openhands serve	openhands web
Interface	Full web GUI	TUI in browser
Dependencies	Docker required	None
Resources	Full container (~2GB)	Lightweight
Features	All GUI features	CLI features only
Best for	Rich GUI experience	Quick terminal access

Troubleshooting

Docker Not Running

❌ Docker daemon is not running.
Please start Docker and try again.

Solution: Start Docker Desktop or the Docker daemon.

Permission Denied

Got permission denied while trying to connect to the Docker daemon socket

Solution: Add your user to the docker group:

sudo usermod -aG docker $USER
# Then log out and back in

Port Already in Use

If port 3000 is already in use, stop the conflicting service or use a different setup. Currently, the port is not configurable via CLI.

See Also

• Local GUI Setup - Detailed GUI setup guide
• Web Interface - Lightweight browser access
• Docker Runtime - Docker configuration details