Skip to main content

​
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

OptionDescription
--mount-cwdMount the current working directory into the container
--gpuEnable 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:

​
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

Featureopenhands serveopenhands web
InterfaceFull web GUITUI in browser
DependenciesDocker requiredNone
ResourcesFull container (~2GB)Lightweight
FeaturesAll GUI featuresCLI features only
Best forRich GUI experienceQuick 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