CodeHero PRO — User Guide

Complete guide to using the CodeHero platform for AI-powered software development.

1. Login & Dashboard

Login

Open your browser and navigate to https://YOUR_IP:9453. You'll see the login page.

Login Page
Login Page

Default credentials:

Important: Change default passwords after first login using: sudo /opt/codehero/scripts/change-passwords.sh

Two-Factor Authentication (2FA): If enabled in settings, you'll be prompted for a 6-digit code from Google Authenticator. Use "Remember this device" to skip 2FA on trusted devices until end of month.

Account Lockout: After 5 failed login attempts, the account is locked for 15 minutes.

Dashboard

The Dashboard is your main control center showing real-time system status.

Dashboard
Dashboard

Dashboard elements:

2. Creating Projects

Projects Page

The Projects page shows all your development projects in a card grid layout.

Projects List
Projects List

Each project card displays: project name, type, description, working directory path, open ticket count, provider/model, and quick action buttons.

Create New Project

Click "+ New Project" to open the creation modal.

Create Project
Create Project Modal
FieldRequiredDescription
NameYesDescriptive project name
Project TypeYesweb, app, api, cli, library
Tech StackYesphp, node, react, python, java, etc.
DescriptionYesBrief description of the project
Web/App PathNoWorking directory (auto-generated)
ProviderNoAI provider (anthropic, gemini, openai, etc.)
AI ModelNoDeveloper role (master/senior/junior)
Think ModeNoExtended thinking level
Execution ModeNoDefault for new tickets
Project TypeDefault Path
web (PHP, HTML)/var/www/projects/{name}
app, api, cli, library/opt/apps/{name}

3. Importing Projects

Import existing projects from ZIP, Git, or local path.

Import Project
Import Project Modal
ModeDescriptionUse When
extendCopy files into project pathContinue developing the project
referenceStore separately as templateBuild something similar
SourceExamples
ZIPURL or local path to ZIP file
GitRepository URL (public or private)
PathLocal folder path (fastest for large projects)

Git Private Repositories

PlatformUsernameToken Type
GitHubOptionalPersonal Access Token (PAT)
GitLabNot neededPersonal Access Token
BitbucketRequiredApp Password

4. Project Detail Page

Click on any project to view its detail page. The page is organized in collapsible sections.

Overview

Project Overview
Project Overview

The top section shows project info (name, type, tech stack, description), database connection details with copy buttons, preview URL, quick action buttons (Code Editor, Git Manager, Progress Dashboard, phpMyAdmin, Export, Context Settings, Archive), and usage statistics (tokens, time, completed tickets).

Production Deployment

Deploy the project to a production-ready nginx config with its own domain or subdomain. Includes SSL certificate management.

Container Isolation (LXC)

Run the project in its own isolated LXC container with dedicated services. See Section 31 for full details.

PHP Settings

Configure the host-level PHP version and .user.ini for projects running directly on the host via nginx:

Note: For container-based projects, runtimes are managed from the Services tab instead.

Context Settings

Customize the AI context for this project: select tech stack to load defaults, edit global context (universal rules) and project context (language-specific patterns).

Project Files

Project Files
Upload Files & Project Files

Upload files via drag & drop, browse the directory tree with folder navigation, delete files, and use the subdirectory filter. Includes Refresh and Pop Out (open in new window) buttons.

Database Editor

Database Editor
Database Editor

Each project gets its own MySQL database. Four tabs: Tables (clickable cards with row counts), Structure (column definitions), Data (browse with pagination), SQL Query (run queries directly).

Backup & Restore

Backup & Restore
Backup & Restore
LevelContentsUse case
Quick (files+DB)Project files and database dumpFast daily backups
Full (+ services)Files, DB, container services and databasesFull project state
Complete (+ tickets)Everything plus tickets and conversationsMigration between servers

Additional features: container image export/import, backup history with download/restore/delete, and upload & restore from another server.

Danger Zone

Delete the project and all its data. A backup is created automatically before deletion.

5. Project Settings & Context

Project Context

Each project has an AI context that helps the AI understand the codebase:

Project Settings

Edit project settings from the project detail page: change provider, AI model, think mode, update description and context, set default execution mode, configure auto-commit and auto-push for git.

6. Creating Tickets

Tickets are the core workflow unit. Each ticket represents a task for the AI to complete.

Create Ticket
Create Ticket
FieldRequiredDescription
TitleYesShort description of the task
DescriptionYesDetailed instructions for the AI
TypeNoCategory (feature, bug, task, etc.)
PriorityNolow, medium, high, critical
ProviderNoOverride project's provider
AI ModelNoOverride project's developer role
Think ModeNoOverride project's think mode
Execution ModeNoOverride project's execution mode
Sequence OrderNoExecution order number
DependenciesNoTickets that must complete first
Parent TicketNoCreate as sub-ticket
Max RetriesNoAuto-retry count (default: 3)

Tickets Page

Tickets List
Project Tickets

Features: drag-and-drop reordering, filter by status/type/priority, bulk actions, and sequence visualization.

7. Ticket Types & Priority

Ticket Types

TypeColorUse For
featurePurpleNew functionality
bugRedFix broken behavior
debugOrangeInvestigation, troubleshooting
rndVioletResearch & Development
taskGrayGeneral work (default)
improvementCyanRefactoring, optimization
docsGreenDocumentation

Priority

PriorityWhen to Use
criticalUrgent, blocks other work
highImportant, do soon
mediumNormal priority (default)
lowNice to have

8. Execution Modes

Control how much freedom the AI has when working on tickets.

ModeDescription
AutonomousFull access, no permission prompts. AI works uninterrupted. Default
Semi-AutonomousSmart sandbox. Auto-approves safe operations, asks for risky ones, blocks dangerous.
SupervisedAI asks permission before every write/edit/bash operation.

Semi-Autonomous Mode Details

Auto-Approved (no prompts)

Requires Approval

Blocked

"Approve Similar" Feature: When a permission prompt appears, click "Approve All Similar" to auto-approve future similar operations in the same ticket.

9. Sequencing & Dependencies

Sequence Numbers

Control execution order: assign a number (1, 2, 3...) to each ticket. Lower numbers run first. Same number = run in parallel (up to 5 tickets per project).

sequence_order=1: [Setup DB, Install deps]     → Run in PARALLEL
sequence_order=2: [Build auth]                  → Waits for seq=1
sequence_order=3: [Users API, Products API]     → Run in PARALLEL

Relaxed vs Strict Mode

ModeBehavior
RelaxedDependent tickets can start when parent reaches awaiting_input or done
StrictDependent tickets wait only for done status

10. Sub-tickets & Parent Tickets

Break complex tasks into smaller pieces:

  1. Create a main (parent) ticket
  2. Create sub-tickets with Parent Ticket set to the main ticket
  3. Sub-tickets inherit project context + receive parent's conversation summary

Sub-tickets wait for parent to complete first, then receive context from parent's title, description, and last 50 messages.

11. Ticket Lifecycle & Actions

Ticket Statuses

StatusDescription
openWaiting to be processed
in_progressAI is currently working
awaiting_inputAI needs your response
doneSuccessfully completed
failedSomething went wrong
skippedManually skipped
timeoutExceeded max duration

Ticket Detail

Ticket Detail
Ticket Detail Page

Ticket Conversation

Ticket Conversation
Ticket Conversation

Actions

ButtonWhat it does
Start NowJump to front of queue
RetryRetry a failed ticket
SkipSkip this ticket
DeletePermanently delete ticket
StopKill switch — stop AI immediately
Send MessageAdd instructions (reopens if awaiting)

12. Auto-Retry

Failed tickets can automatically retry. Each ticket has retry_count (starts at 0) and max_retries (default 3). When a ticket fails, retry_count increments. If retry_count < max_retries, the ticket resets to open and tries again.

13. Multi-Provider Support

CodeHero supports multiple AI providers simultaneously. Different tickets can use different providers.

ProviderModelsBest For
AnthropicClaude Opus, Sonnet, HaikuBest overall quality
Google Gemini2.5 Pro, 2.5 FlashCost-effective, vision
OpenAIGPT-4o, o1, o3Strong reasoning
xAI GrokGrok-3, Grok-3-miniFast, good value
DeepSeekV3, R1Very cheap, backend
GLMGLM-4, CogViewChinese language, vision
OpenRouterMultiple modelsAccess to many models
OllamaLocal modelsFree, private, offline
vLLMSelf-hostedFree, custom models

Cost Weights (1-10, lower = cheaper)

ProviderMasterSeniorJunior
Anthropic1062
OpenAI952
Grok844
Gemini521
DeepSeek311
GLM321
OpenRouter531
Ollama000
vLLM000

Smart Weights (1-10, higher = better reasoning)

ProviderMasterSeniorJunior
Anthropic1086
OpenAI975
DeepSeek966
Gemini864
Grok866
GLM877
OpenRouter975
Ollama554
vLLM554
Rate Limit Strategy: When running parallel tickets, distribute across providers to avoid rate limits.

14. Developer Roles

RoleBest ForModels
master_developerComplex architecture, critical decisionsTop-tier (Opus, GPT-4o)
senior_developerFeatures, integrationsMid-tier (Sonnet, Gemini Pro)
junior_developerSimple tasks, boilerplate, docsFast/cheap (Haiku, Flash)

Role Assignment by Complexity

Complexityecobalancedperformance
Trivial (docs, typos)juniorjuniorjunior
Simple (basic features)juniorjuniorsenior
Moderate (features, APIs)juniorseniorsenior
Complex (refactoring)seniorseniormaster
Critical (architecture)seniormastermaster

15. Think Mode (Extended Thinking)

ModeDescriptionBest For
offNo extended thinkingSimple tasks
basicLight reasoningStandard features
balancedModerate analysisMost tasks (default)
ultraDeep reasoningComplex architecture, debugging

Provider Types

TypeProvidersHow It Works
Type AAnthropic, GeminiConfigurable token budget
Type BOpenAIMaps to reasoning levels (low/medium/high)
Type CDeepSeek, GLM, Grok, OpenRouterBinary: on or off
NoneOllama, vLLMNo thinking support

16. Vision Support

Some providers can "see" — analyze screenshots, UI layouts, and visual content.

ProviderVisionUse For
AnthropicYesUI verification, styling, visual QA
GeminiYesUI verification, styling
GLMYesUI verification (auto-switches model)
GrokYesUI verification
OpenAIYesUI verification
OpenRouterDependsDepends on underlying model
DeepSeekNoBackend only
OllamaNoBackend only
vLLMNoBackend only
For web projects: Use vision-capable providers for HTML/CSS/UI tasks. DeepSeek is fine for backend-only work.

17. Code Editor

The built-in Monaco Editor provides VS Code-quality editing in your browser.

Code Editor
Code Editor
Setup LSP: Run sudo /opt/codehero/scripts/setup_lsp.sh to install language servers for full IDE features.

18. File Explorer

File Explorer
File Explorer

19. Git Manager

Full version control through the web interface.

Git Manager
Git Manager - Repositories

CodeHero automatically detects Git repositories in your project directory. Multiple repos per project are supported.

Clone & Init

Clone Repository
Clone Repository

Clone remote repositories (HTTPS/SSH), initialize new repos, and store Git credentials per repository.

Changes & Commits

Git Changes
Changes & Commits

Status overview, stage/unstage files individually or all at once, commit with message editor, and inline diff viewer.

Branches

Git Branches
Branches

View local and remote branches, create, checkout, merge with conflict resolution, and delete.

Tags

Git Tags
Tags

View, create (lightweight and annotated), push, and delete tags.

History

Git History
Commit History

Commit log with author, date, message. Diff viewer per commit. Revert specific commits. Reset to any commit (soft/mixed/hard).

Stash

Git Stash
Stash

Stash current changes, list stashes, apply/pop, and drop.

Diff Viewer

Diff Viewer
Fullscreen Diff Viewer

Full-screen diff with inline or side-by-side comparison, syntax highlighting, and line-by-line navigation.

Backup History

Git Backup
Backup History

Auto-Commit & Auto-Push

Configure per repository: auto-commit when AI completes a ticket, auto-push after auto-commit.

Settings

Git Settings
Repository Settings

Remote URL management, credentials, auto-commit/auto-push toggles, default branch configuration.

20. Console (Real-time Output)

Console
Console

21. Web Terminal

Web Terminal
Web Terminal

22. Package Manager

Package Manager
Package Manager
PackageWhat It Installs
Development ToolsNode.js 22, Java (GraalVM 24), ffmpeg, ImageMagick, tesseract
Android DevelopmentDocker, Redroid emulator, ws-scrcpy, ADB, Flutter, Gradle
Windows/.NET.NET 8 SDK, PowerShell 7, Wine, Mono, NuGet
Code Editor LSPLanguage servers for Python, JS/TS, PHP, Java, C#, Kotlin, HTML/CSS

23. Session History

Session History
Session History

View all past AI execution sessions: start/end times, duration, exit codes (0 = success), associated ticket, token usage, and full session log. Filter by date, project, or status.

24. Project Progress

Project Progress
Project Progress

Visual overview: completion percentage, ticket counts by status/type, sequence flow visualization, model distribution, and built-in AI assistant for project-specific chat.

25. Kill Switch

Instantly stop the AI when it's working on a ticket.

MethodHow
Stop ButtonRed button appears when ticket is in_progress
/stop CommandType /stop in the chat field
AI AssistantAsk: "Stop ticket PROJ-0001"

What happens: AI process receives SIGTERM, ticket status changes to awaiting_input, you can provide new instructions or corrections.

26. AI Assistant

AI Assistant
AI Assistant

AI Project Manager

From the Projects page, click "Plan with AI" to start a guided project planning session. The AI suggests architecture, generates ticket plans with dependencies, and creates all tickets.

27. Telegram Notifications

Setup

  1. Create a Telegram Bot via @BotFather — send /newbot, copy the token
  2. Start a chat with your bot and send a message
  3. Get your Chat ID from https://api.telegram.org/bot<TOKEN>/getUpdates
  4. Configure in Settings — paste Bot Token and Chat ID, select notification types, Test & Save

Notification Types

EventDescription
Awaiting InputAI completed and needs review
Task FailedSomething went wrong
Watchdog AlertTicket appears stuck

Two-Way Communication

Reply directly to notifications from your phone. Start with ? for status queries without reopening the ticket.

28. Settings & Configuration

Settings
Settings

Access all configuration from the Settings button in the header. The modal has 7 tabs:

Settings (General)

License

View license status, activation date, and expiry. Enter or update your license key.

Certificates

Domains

Configure custom domains for the dashboard and web project previews. The system auto-configures Nginx virtual hosts.

heroagent.conf

Edit the main agent configuration file directly. Controls model aliases, token limits, provider settings, and daemon behavior. Auto-backup is created before each save.

system.conf

Edit system-level configuration: Nginx settings, PHP-FPM settings, and other server parameters.

Security

29. System Updates

Dashboard Update

  1. A green "Update Available" badge appears in the header
  2. Click to see release notes
  3. Click "Install Update"
  4. Watch real-time console output
  5. Page auto-reloads on success

Command Line Update

cd /root
# Extract the ZIP file provided with your CodeHero PRO license
unzip codehero-pro-release-4.6.3.zip
cd codehero
sudo ./upgrade.sh
OptionDescription
--dry-runPreview changes without applying
-y, --yesAuto-confirm all prompts

30. Config File Editor

Edit system configuration files directly from the web interface:

Features: syntax-highlighted editor, auto-backup before saving, restore from backup, validation before apply.

31. Container Isolation (LXC)

Run each project in its own LXC container with a full service stack. Since v4.6.3, containers include a Service Manager for installing web apps, databases, and caches from a built-in catalog.

Container Panel
Container panel with status, controls, and snapshots

Setting Up a Container

  1. Go to Project Detail page
  2. Scroll to Container Isolation (LXC) section
  3. Select Base Image (Ubuntu 24.04 recommended), Disk Size (5-50 GB)
  4. Optionally enable Auto-Snapshot and DB Migration
  5. Click "Create Container"

Container Management

ActionDescription
Start / StopBoot or gracefully shut down the container
Resize DiskIncrease BTRFS volume size
SnapshotInstant BTRFS snapshot with automatic DB freeze
Migrate DBMove host database into the container
DestroyRemove container and all data
Auto-start on server bootToggle to automatically start the container when the server reboots (enabled by default)

Snapshots

BTRFS snapshots provide instant backup and restore:

Container Services

The Service Manager (v4.6.3+) lets you install, control, and manage services inside the container without touching the command line.

Container Services
Services table with running status indicators and action buttons

Installing Web Apps

  1. Click "+ Add Service"Web App
  2. Select Language, Version, Server/Framework, and Path
  3. Click Install
Install Web App
One-click web app installation from catalog

Supported Languages & Frameworks

LanguageVersionsFrameworks
PHP7.4 – 8.4php-fpm, Laravel, Symfony, WordPress
Python3.8 – 3.13Flask, Django, FastAPI, Gunicorn, uWSGI
Node.js18, 20, 22Express, NestJS, Next.js, PM2
Go1.21 – 1.23Gin, Echo, Fiber
Ruby3.2 – 3.4Puma, Rails, Sinatra
Java8, 11, 17, 21Spring Boot, Tomcat
.NET6.0 – 10.0Kestrel
Multi-runtime: Multiple languages can run side by side in the same container, each on a different URL path.

Installing Databases & Caches

  1. Click "+ Add Service"Database
  2. Select Database type and Version
  3. Click Install
Install Database
Database installation with auto-configured port

Supported Databases

DatabaseVersionsPortManagement Tool
MySQL5.7, 8.0, 8.43306phpMyAdmin
MariaDB10.11, 11.43306phpMyAdmin
PostgreSQL14 – 175432pgAdmin
MongoDB8.027017Mongo Express
MSSQL2022, 20251433

Caches

CacheVersionPortPersistence
Redis76379RDB snapshots
Memcached1.611211None (memory only)

Service Control

Each service has action buttons: Start, Stop, Restart, Delete. Bulk actions at the top: Stop All, Start All, Refresh Status, Full Backup.

Database Backup & Restore

Database services support Backup (timestamped native format), Restore (from backup file), and Full Backup (all databases at once). Backups can be downloaded from the web interface.

Tip: Combine database backups with BTRFS snapshots for comprehensive disaster recovery.

Password Management

Database credentials are auto-generated during installation. Change passwords anytime — connection scripts and backup scripts are automatically updated.

Container Terminal

Full shell access inside the container with three modes: Inline (embedded), Popup (new window), Full Page (full-screen). Uses xterm.js with copy/paste support.

Container Terminal
Web terminal with full shell access inside container

When to Use Containers

ScenarioRecommendation
Simple static websitesContainer not needed
Projects needing specific runtime versionsUse containers
Projects requiring databasesUse containers
Client projects needing isolationUse containers
Multi-service architecturesUse containers

32. Production Deployment

Deploy CodeHero behind a production-ready setup with custom domains and SSL.

Nginx Reverse Proxy

Set up Nginx on your server to proxy to CodeHero:

server {
    listen 80;
    server_name codehero.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name codehero.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/codehero.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/codehero.yourdomain.com/privkey.pem;

    location / {
        proxy_pass https://127.0.0.1:9453;
        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;
    }

    # WebSocket support (for console, terminal)
    location /socket.io/ {
        proxy_pass https://127.0.0.1:9453/socket.io/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Domain Setup

  1. Point your domain's DNS A record to your server IP
  2. Configure the domain in Settings → Domains tab
  3. The system will automatically configure Nginx

SSL Certificates

Let's Encrypt (Recommended):

  1. Go to Settings → Certificates
  2. Enter your domain name
  3. Click "Request Certificate"
  4. Certificates auto-renew every 90 days

Custom Certificate:

  1. Go to Settings → Certificates
  2. Select "Upload Custom"
  3. Provide your certificate (.pem) and private key

Firewall Rules

sudo ufw allow 80/tcp    # HTTP (redirect to HTTPS)
sudo ufw allow 443/tcp   # HTTPS
sudo ufw allow 9453/tcp  # CodeHero Dashboard
sudo ufw allow 9867/tcp  # Web Project Previews

33. Tips & Best Practices

Writing Good Tickets

Do:

Don't:

Good example:

Title: Add user authentication API

Description:
Create REST API endpoints in /api/auth/:
- POST /api/auth/login - Accept email/password, return JWT
- POST /api/auth/register - Create new user
- GET /api/auth/me - Return current user (requires auth)

Use the existing User model in models/user.py.
Use bcrypt for password hashing.

Bad example:

Title: Auth
Description: Add login

Parallel Execution

Cost Optimization

34. Troubleshooting

Ticket Stuck in "in_progress"

  1. Check Console for errors
  2. Use Kill Switch (Stop button or /stop)
  3. Retry the ticket

AI Not Processing Tickets

  1. Check daemon: systemctl status codehero-daemon
  2. Review logs: journalctl -u codehero-daemon -f
  3. Verify MySQL: systemctl status mysql
  4. Restart: sudo systemctl restart codehero-web codehero-daemon

Permission Errors

Can't Access Dashboard

  1. Check services: systemctl status codehero-web nginx
  2. Check firewall: sudo ufw allow 9453
  3. Verify IP: hostname -I
  4. Browser may block self-signed cert

Provider API Errors

35. Keyboard Shortcuts

Code Editor

ShortcutAction
Ctrl+SSave file
Ctrl+ZUndo
Ctrl+Shift+ZRedo
Ctrl+FFind
Ctrl+HFind and Replace
Ctrl+GGo to line
Ctrl+DSelect next occurrence
Ctrl+/Toggle comment
Alt+Up/DownMove line up/down
Ctrl+Shift+KDelete line
Ctrl+ClickGo to definition

Web Terminal

ShortcutAction
Ctrl+CInterrupt command
Ctrl+DExit shell
Ctrl+LClear terminal
Ctrl+Shift+CCopy selection
Ctrl+Shift+VPaste

General

ShortcutAction
EscapeClose modal