Codehive

Persistent AI coding agent workspace with sub-agent orchestration. Agents live in projects, execute tasks autonomously, create sub-agents, and are accessible from web, mobile, Telegram, and terminal. Not a chat -- an operating system for agent sessions.

How It Works

Codehive is a self-hosted tool that runs on your own server or computer. There is no hosted version -- you own your instance entirely.

1. Install codehive on your server (or laptop, or home machine)
2. SSH in and run codehive serve to start the backend
3. Connect from your clients via SSH port forwarding:

   ssh -L 7433:localhost:7433 yourserver

4. Open http://localhost:7433 in your browser, or point the mobile app at it

One user, one instance. Your code and agent data never leave your machine. The backend only listens on 127.0.0.1 — remote access is handled by SSH tunnels on the client side, not by the backend.

Architecture

Monorepo with three top-level directories:

backend/    Python 3.13, FastAPI, SQLAlchemy, Redis
web/        React 19, Vite, TypeScript, Tailwind CSS
mobile/     (planned)

Prerequisites

• Python 3.12+
• Node.js 20+
• uv (Python package manager)
• Git

Quick Start (SQLite — zero infrastructure)

No Docker, no PostgreSQL, no Redis needed. Just Python and Node.

Codehive supports multiple LLM providers:

Provider	Type	Setup
Claude	CLI	Install claude CLI -- no API key needed
Codex	CLI	Install codex CLI -- no API key needed
OpenAI API	API	Set CODEHIVE_OPENAI_API_KEY in .env
Z.ai	API	Set CODEHIVE_ZAI_API_KEY in .env

# 1. Clone and enter the repo
git clone <repo-url> && cd codehive

# 2. Copy and edit environment config
cp .env.example .env
# If using Claude CLI (default), no API keys needed.
# For Z.ai: uncomment and set CODEHIVE_ZAI_API_KEY in .env
# For OpenAI API: uncomment and set CODEHIVE_OPENAI_API_KEY in .env

# 3. Install dependencies
cd backend && uv sync --dev && cd ..
cd web && npm install && cd ..

# 4. Start both servers with a single command
cd backend
uv run codehive dev

This starts the backend (uvicorn with auto-reload on http://127.0.0.1:7433) and the frontend dev server (http://localhost:5173) together. Press Ctrl+C to stop both. You can also start them separately:

uv run codehive dev --no-frontend   # backend only
uv run codehive dev --no-backend    # frontend only

Data is stored in backend/data/codehive.db (SQLite, auto-created on first run).

Quick Start with PostgreSQL + Redis (optional)

For production or multi-process deployments:

# Start infrastructure
docker compose up -d

# Set database URL in .env
echo "CODEHIVE_DATABASE_URL=postgresql+asyncpg://codehive:codehive@localhost:5432/codehive" >> .env
echo "CODEHIVE_REDIS_URL=redis://localhost:6379/0" >> .env

# Start the backend
cd backend && uv sync --dev && uv run codehive serve

Terminal-only mode (no web server needed)

cd backend
uv run codehive code           # start agent in current directory
uv run codehive code ~/myapp   # start agent in a specific directory

This launches a Textual TUI with streaming, markdown rendering, and tool approval prompts. If the backend is running, sessions are shared with the web UI. If not, it runs standalone with a local engine.

Default Login

On first run the server creates an admin user. Credentials are controlled by environment variables:

Variable	Default
CODEHIVE_ADMIN_USERNAME	admin
CODEHIVE_ADMIN_PASSWORD	random (printed to server logs)

Set CODEHIVE_ADMIN_PASSWORD=admin in your .env for a known password. If the admin was already created and you forgot the password, reset the DB:

docker exec codehive-postgres-1 psql -U codehive -d codehive \
  -c "DELETE FROM workspace_members; DELETE FROM users; DELETE FROM workspaces;"

Then restart uv run codehive serve — it will re-seed with your configured credentials.

Backend

cd backend
uv sync --dev          # Install dependencies
uv run codehive serve  # Start the API server

Options:

--host HOST    Bind address (default: 127.0.0.1)
--port PORT    Bind port (default: 7433)
--reload       Enable auto-reload for development

The server can also be configured via environment variables (see below).

Database Migrations

cd backend
uv run alembic upgrade head    # Apply migrations
uv run alembic revision -m "description" --autogenerate  # Create a new migration

Web App

cd web
npm install        # Install dependencies
npm run dev        # Start dev server (http://localhost:5173)
npm run build      # Production build
npm run preview    # Preview production build
npm run lint       # Run ESLint

TUI (Terminal Interface)

Interactive terminal dashboard, designed to work over SSH and on small screens.

cd backend
uv run codehive tui       # Full interactive dashboard
uv run codehive rescue    # Rescue mode (emergency controls)

Rescue mode provides emergency access to stop runaway sessions, kill agents, rollback checkpoints, and toggle maintenance mode.

Telegram Bot

Lightweight client for monitoring sessions, answering questions, and approving actions.

# Set the bot token
export CODEHIVE_TELEGRAM_BOT_TOKEN=your-token-here

cd backend
uv run codehive telegram

Create a bot via @BotFather on Telegram to get your token.

CLI Commands

All commands are available via codehive (or uv run codehive from the backend/ directory).

Command	Description
codehive dev	Start backend + frontend dev servers together
codehive code [directory]	Start a lightweight coding agent session
codehive serve	Start the API server
codehive tui	Launch interactive terminal dashboard
codehive rescue	Launch rescue mode (emergency TUI)
codehive telegram	Start the Telegram bot
codehive projects list	List all projects
codehive projects create NAME --workspace ID	Create a project
codehive sessions list --project ID	List sessions for a project
codehive sessions create PROJECT_ID --name NAME	Create a session
codehive sessions status SESSION_ID	Show session details
codehive sessions chat SESSION_ID	Interactive chat with a session
codehive sessions pause SESSION_ID	Pause a session
codehive sessions rollback SESSION_ID --checkpoint ID	Rollback to checkpoint
codehive questions list	List pending questions
codehive questions answer QUESTION_ID "answer"	Answer a question
codehive system health	Show system health status
codehive system maintenance on|off	Toggle maintenance mode

Use --base-url URL on any command to point at a different server (default: http://127.0.0.1:7433). This can also be set via CODEHIVE_BASE_URL.

Running Tests

Backend

cd backend
uv run pytest tests/ -v            # Run all tests
uv run pytest --cov=codehive --cov-report=term-missing  # With coverage
uv run ruff check                  # Lint
uv run ruff format --check         # Check formatting

Web

cd web
npx vitest          # Run tests
npm run lint        # Lint

Environment Variables

Copy .env.example to .env and fill in your values. DB and Redis defaults match docker-compose.yml -- no changes needed for local dev.

CODEHIVE_HOST=127.0.0.1          # API bind address
CODEHIVE_PORT=7433               # API bind port
CODEHIVE_DEBUG=false             # Auto-reload
CODEHIVE_DATABASE_URL=postgresql+asyncpg://codehive:codehive@localhost:5432/codehive
CODEHIVE_REDIS_URL=redis://localhost:6379/0

# LLM Providers (set the ones you use)
CODEHIVE_OPENAI_API_KEY=         # For OpenAI API provider
CODEHIVE_OPENAI_BASE_URL=        # Optional custom OpenAI API URL
CODEHIVE_ZAI_API_KEY=            # For Z.ai provider
CODEHIVE_ZAI_BASE_URL=           # Optional custom Z.ai API URL

# Other integrations
CODEHIVE_TELEGRAM_BOT_TOKEN=     # For `codehive telegram`
CODEHIVE_TELEGRAM_CHAT_ID=       # For Telegram notifications
CODEHIVE_GITHUB_DEFAULT_TOKEN=   # For GitHub integration

Infrastructure

Start and stop PostgreSQL and Redis via Docker Compose:

docker compose up -d       # Start
docker compose down        # Stop
docker compose ps          # Status

Or from the backend directory using Make:

cd backend
make infra-up       # Start
make infra-down     # Stop
make infra-status   # Status

License

WTFPL