Skip to main content
The OpenHands CLI is no longer actively maintained. These instructions are retained for legacy users. For a maintained local installation, use Agent Canvas with npm, npx, or Docker.

Overview

The openhands serve command launches the full OpenHands GUI server using Docker. This runs the legacy Docker-based GUI locally; it does not launch Agent Canvas.
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

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

Mounting Your Workspace

To give OpenHands access to your local files:
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:
This requires:

Examples

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

Troubleshooting

Docker Not Running

Solution: Start Docker Desktop or the Docker daemon.

Permission Denied

Solution: Add your user to the docker group:

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