Server

Server#

gptme provides multiple web-based interfaces for browser-based interactions, from lightweight options to sophisticated desktop-integrated experiences.

Installation#

To use gptme’s server capabilities, install with server extras:

pipx install 'gptme[server]'

Start the server:

gptme-server

For more CLI options, see the CLI reference.

gptme-webui: Modern Web Interface#

The primary web interface is gptme-webui: a modern, feature-rich application that provides a complete gptme experience in your browser. (Originally a standalone repo, now merged into the main gptme repository.)

Try it now:

  • chat.gptme.org (latest version of gptme-webui, bring your own gptme-server)

  • gptme.ai (upcoming hosted gptme service)

Key Features:

  • Modern interface

  • Streaming responses

  • Mobile-friendly responsive design

  • Dark mode support

  • Conversation export and offline capabilities

  • Integrated computer use interface

  • Create your own persistent agents

Local Installation: For self-hosting and local development, see the gptme-webui README.

To use the server with a locally hosted gptme-webui, configure the CORS origin when starting the server:

gptme-server --cors-origin 'http://localhost:5701'

Note

Connecting the hosted web UI to a local server (Chrome 142+). When you use the hosted web UI at chat.gptme.org with a gptme-server running on localhost, recent Chromium browsers (Chrome 142+) gate the connection behind a Local Network Access permission prompt. This check runs before CORS headers are evaluated, so the --cors-origin flag is necessary but no longer sufficient — you must also click Allow on the permission prompt for the page to reach your local server. Serving the web UI from a local origin (for example http://localhost:5701) avoids the prompt entirely, since that is a local-to-local request.

Self-Hosting with Docker Compose#

For a self-contained deployment, a docker-compose.yml is included at the repository root. It builds a lean image (scripts/Dockerfile.selfhost, gptme + the server extra only — no Node/agent tooling) and runs gptme-server with persistent volumes for config and conversation logs.

# Clone the repository
git clone https://github.com/gptme/gptme.git
cd gptme

# Configure: at least one provider key is required
cp .env.example .env
$EDITOR .env

# Build and start the server
docker compose up --build

The server listens on http://localhost:5700.

The simplest way to use it is the basic web UI the server bundles at the same origin — just open http://localhost:5700 in a browser. Being same-origin, it needs no CORS setup (you will still need the server token; see below).

To use the full-featured hosted web UI instead, open chat.gptme.org and point it at your server. That is a cross-origin setup, so the server must allow the UI’s origin — the default CORS_ORIGIN already permits chat.gptme.org. Set CORS_ORIGIN in .env to a different origin if you self-host the web UI yourself.

Key .env settings:

  • OPENAI_API_KEY / ANTHROPIC_API_KEY / OPENROUTER_API_KEY — at least one is required.

  • GPTME_SERVER_TOKEN — auth token. The server enables auth by default when bound to 0.0.0.0 (as in the container), so set this and configure the web UI with the same value. If left blank, a token is auto-generated at startup — find it with docker compose logs.

  • CORS_ORIGIN — origin allowed to call the server (defaults to the hosted web UI).

  • GPTME_SERVER_PORT — host port to publish (the container always listens on 5700).

Production Deployment: nginx Reverse Proxy#

The docker-compose setup above publishes the server on a plain HTTP port (5700 by default). For a public-facing deployment you should put it behind a reverse proxy that terminates TLS and forwards requests to the container. The example below uses nginx with a Let’s Encrypt certificate.

Warning

Do not expose the raw 5700 port to the internet. Bind the published port to loopback so only the proxy can reach it. In .env (or docker-compose.yml) set the publish address to 127.0.0.1:

ports:
  - "127.0.0.1:5700:5700"

Also set GPTME_SERVER_TOKEN to a strong value — the proxy handles TLS, but the token is what authenticates each request.

1. Obtain a TLS certificate with certbot (one-time, then auto-renewed):

sudo apt install certbot python3-certbot-nginx
sudo certbot certonly --nginx -d gptme.example.com

Note

The --nginx plugin handles the ACME HTTP challenge through nginx itself, so you do not need to stop nginx first (unlike --standalone, which binds its own listener to port 80 and fails when nginx is already running).

2. nginx site config (/etc/nginx/sites-available/gptme):

server {
    listen 80;
    server_name gptme.example.com;
    # Redirect all HTTP to HTTPS
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name gptme.example.com;

    ssl_certificate     /etc/letsencrypt/live/gptme.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/gptme.example.com/privkey.pem;

    # Restrict to TLS 1.2/1.3 with strong ciphers (Mozilla "intermediate" profile)
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;

    location / {
        proxy_pass http://127.0.0.1:5700;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # gptme-server streams responses over Server-Sent Events
        # (text/event-stream). Disable proxy buffering and use long
        # read timeouts so streamed tokens are flushed to the client
        # immediately rather than buffered until the response completes.
        proxy_buffering    off;
        proxy_cache        off;
        proxy_read_timeout 3600s;
        proxy_set_header   Connection "";
        proxy_http_version 1.1;
    }
}

3. Enable the site and reload nginx:

sudo ln -s /etc/nginx/sites-available/gptme /etc/nginx/sites-enabled/
sudo nginx -t        # validate config
sudo systemctl reload nginx

The server is now reachable at https://gptme.example.com. Point your web UI (or the hosted UI at chat.gptme.org) at that URL, and set CORS_ORIGIN in .env to the origin the UI is served from.

Note

The proxy_buffering off and long proxy_read_timeout settings are the important part: without them nginx buffers the SSE stream and the chat appears to hang until each full response is ready, instead of streaming token by token.

Local-only access. If you only want the server reachable from the host itself (for example, behind a VPN or an SSH tunnel), skip the proxy entirely and keep the default loopback bind — open an SSH tunnel from your client with ssh -L 5700:127.0.0.1:5700 user@host and use http://localhost:5700.

Running as a systemd Service (pipx)#

If you installed gptme directly with pipx rather than Docker, you can run the server as a systemd service so it starts on boot and restarts on failure. A ready-to-edit unit template ships at scripts/gptme-server.service.

The template runs the server as a dedicated gptme user, reads secrets from /etc/gptme/server.env, binds loopback, and applies systemd hardening (ProtectSystem=strict, NoNewPrivileges, etc.). Install it with:

# Dedicated service user + pipx install of the entrypoint
sudo useradd --system --create-home --shell /usr/sbin/nologin gptme
sudo -u gptme pipx install 'gptme[server]'

# Pre-create config/data dirs (required: ProtectHome=read-only only bind-mounts
# paths that already exist; gptme initialises them at import time, which fails
# under the sandbox on a fresh install before any request is served)
sudo -u gptme mkdir -p /home/gptme/.config/gptme \
                       /home/gptme/.local/share/gptme \
                       /home/gptme/.local/state/gptme

# Secrets file (provider keys, optional GPTME_SERVER_TOKEN), not world-readable
sudo install -d -m 750 -o gptme -g gptme /etc/gptme
sudo install -m 640 -o gptme -g gptme /dev/null /etc/gptme/server.env
sudoedit /etc/gptme/server.env   # add ANTHROPIC_API_KEY=... etc.

# Download and install the unit (adjust User=, the ExecStart path, --cors-origin)
sudo curl -fsSL https://raw.githubusercontent.com/gptme/gptme/master/scripts/gptme-server.service \
    -o /etc/systemd/system/gptme-server.service
sudo systemctl daemon-reload
sudo systemctl enable --now gptme-server

Tail logs with journalctl -u gptme-server -f. Because the unit binds 127.0.0.1, pair it with the nginx reverse proxy above to expose it over TLS; on loopback the auth token is optional (set GPTME_SERVER_TOKEN in the env file if you change the bind to a public interface).

Basic Web UI#

A lightweight chat interface with minimal dependencies is bundled with the gptme server for simple deployments.

Access at http://localhost:5700 after starting gptme-server.

This interface provides basic chat functionality and is useful for:

  • Quick testing and development

  • Minimal server deployments

  • Environments with limited resources

Computer Use Interface#

The computer use interface provides an innovative split-view experience with chat on the left and a live desktop environment on the right, enabling AI agents to interact directly with desktop applications.

Warning

The computer use interface is experimental and has serious security implications. Please use with caution and see Anthropic’s documentation on computer use for additional guidance.

Docker Setup (Recommended):

# Clone the repository
git clone https://github.com/gptme/gptme.git
cd gptme

# Build and run the computer use container
make build-docker-computer
docker run -v ~/.config/gptme:/home/computeruse/.config/gptme -p 6080:6080 -p 8080:8080 gptme-computer:latest

Access Points:

Features:

  • Split-view interface with real-time desktop interaction

  • Toggle between view-only and interactive desktop modes

  • Automatic screen scaling optimized for LLM vision models

  • Secure containerized environment

Requirements:

  • Docker with X11 support

  • Available ports: 6080 (VNC) and 8080 (web interface)

Local Computer Use (Advanced)#

You can enable the computer tool locally on Linux systems, though this is not recommended for security reasons.

Requirements:

  • X11 server

  • xdotool package installed

Usage:

# Enable computer tool in addition to default tools
gptme --tools +computer

Set an appropriate screen resolution for your vision model before use.

For long-running visual workflows, prefer a specialized subagent profile to keep parent context smaller:

# Desktop interaction (mouse, keyboard, screenshots)
subagent(
    "computer-use",
    "Click the Submit button, wait for the modal, and screenshot the result",
)

# Web browsing and testing
subagent(
    "browser-use",
    "Open localhost:5173, capture a screenshot, and report UI issues",
)

REST API#

gptme-server provides a REST API for programmatic access to gptme functionality. This enables integration with custom applications and automation workflows.

The API endpoints support the core gptme operations including chat interactions, tool execution, and conversation management.

Note

API documentation is available when running the server. Visit the server endpoint /api/docs/ for interactive API documentation based on the OpenAPI spec (served at /api/docs/openapi.json).