GPTMe Tutorial: Getting Started with Your Terminal AI Agent

Getting Started with GPTMe: From Zero to Autonomous Agent in 10 Minutes

I'll be honest — the first time I tried setting up a terminal AI agent, I expected it to take hours. Config files, API keys, dependency hell. But GPTMe surprised me. Here's the exact walkthrough so you don't waste time on the things I tripped over.

🚀 Deploy GPTMe with Docker?

Full Docker Compose setup with production configs on the tool page.

View GPTMe Tool Page →

Prerequisites

You'll need Python 3.11+ and pip. That's it. I'm on Linux (Ubuntu 24.04), but GPTMe works on macOS too — Windows users might need WSL2.

# Check your Python version
python3 --version
# Should be 3.11 or higher

⚠️ I wasted 15 minutes here: Make sure you have pip installed. On Ubuntu: sudo apt install python3-pip python3-venv. Don't skip this — the install will fail silently otherwise.

Step 1: Install GPTMe

The official install is dead simple — one pip command:

pip install gptme

This installs the CLI tool and all its dependencies. Takes about 30 seconds — go grab a coffee.

💡 Pro tip: Use a virtual environment if you're picky about your system Python. python3 -m venv ~/gptme-env && source ~/gptme-env/bin/activate && pip install gptme. This isolates it from your other packages.

Step 2: Set Up Your API Key

GPTMe needs an LLM provider. I use OpenRouter (one key, many models) but Anthropic and OpenAI work too:

export OPENROUTER_API_KEY="sk-or-v1-your-key-here"
# Or if you prefer Anthropic:
# export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# Quick test — GPTMe should respond
gptme "Hello! What can you do?"

If you see a response — congratulations, it's working. If not, check your API key. I spent 20 minutes debugging once because I had a typo in the key.

Step 3: Try Something Real

Here's what I tested first — and it blew my mind:

# Ask GPTMe to explore your project
gptme "Analyze this project's structure. What's the architecture?
List all dependencies and find any potential issues."

GPTMe will run find, grep, read files, and give you a comprehensive analysis. No manual commands needed.

What I Wish I Knew From Day One

Task	Command	What Happens
Code review	`gptme "Review src/main.py"`	Reads file, analyses, reports issues
Debug	`gptme "Why is this failing?"`	Runs code, reads errors, fixes iteratively
Research	`gptme "What's the latest FastAPI version?"`	Browses web, fetches PyPI, reports
Refactor	`gptme "Split this file into modules"`	Creates files, moves code, tests result

Running with Docker (Headless)

If you want GPTMe running as a service (for the web UI or API access), use the Docker setup:

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

# Copy and edit the environment
cp .env.example .env
# Add your API key(s) to .env

# Start the server
docker compose up --build -d
# Web UI at http://localhost:5700

🔑 Key insight: GPTMe generates an auth token automatically on first start. Check docker compose logs to find it — you'll need it for web UI access.

Final Verdict

After a week of daily use, GPTMe has earned a permanent spot in my workflow. It's not perfect — occasionally it gets stuck in loops, and the web UI is basic — but the core concept is solid. An AI agent that actually lives in your terminal, uses your tools, and remembers context? That's the future. And it's open source.

Give it a shot. Worst case: you uninstall it in 5 minutes. Best case: you wonder how you ever worked without a terminal-native AI agent.

🚀 Explore GPTMe on Run This Ai

Docker Compose configs, system requirements, installation guides, and more — all in one place.

View GPTMe Tool Page →