> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/openhands/usage/cloud/openhands-cloud), but running locally on your machine.

```bash theme={null}
openhands serve
```

<Note>
  This requires Docker to be installed and running on your system.
</Note>

## Prerequisites

* [Docker](https://docs.docker.com/get-docker/) installed and running
* Sufficient disk space for Docker images (\~2GB)

## Basic Usage

```bash theme={null}
# 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:

```bash theme={null}
# 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.

<Tip>
  Navigate to your project directory before running `openhands serve --mount-cwd` to give OpenHands access to your project files.
</Tip>

## GPU Support

For tasks that benefit from GPU acceleration:

```bash theme={null}
openhands serve --gpu
```

This requires:

* NVIDIA GPU
* [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html) installed
* Docker configured for GPU support

## Examples

```bash theme={null}
# 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           | Terminal UI 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:

```bash theme={null}
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](/openhands/usage/run-openhands/local-setup) - Detailed GUI setup guide
* [Web Interface](/openhands/usage/cli/web-interface) - Lightweight browser access
* [Docker Sandbox](/openhands/usage/sandboxes/docker) - Docker sandbox configuration details