Skip to content

local-gui.mdx

Latest commit

 

History

History
138 lines (96 loc) · 3.53 KB

local-gui.mdx

File metadata and controls

138 lines (96 loc) · 3.53 KB
title Local GUI
description 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:

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