AI-Shifu: A Self-Hosted One-on-One Teaching Agent for Course Creators
Get AI to teach and answer questions for you - just by typing!
At a glance
- What is it?
- AI-Shifu turns a single lesson framework into a personalized tutoring session, packaged as a Docker Compose stack with a bundled MySQL service. It is aimed at instructors and training teams who want to run the stack themselves, and its limits show up the moment you need more than one locale or a production-grade login flow.
- Who is it for?
- Adopt AI-Shifu if you are a course creator or training team willing to run Docker Compose, set an LLM API key and treat the first verified user as the administrator of a single-instance deployment. Do not adopt it if you need more than English and Simplified Chinese in the interface, or if you cannot accept that the universal verification code 1024 is the default login path for demos.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Problem AI-Shifu Targets: One Framework, Many Learners
The README states the project is for "creators, instructors, and training/education teams" and describes the pitch as "Write Once, Teach Personally." The problem it addresses is concrete: a single lesson plan has to serve learners with different backgrounds, and the manual work of adapting explanations, asking follow-up questions and checking understanding does not scale past a small cohort. AI-Shifu takes an authored framework plus stated teaching intent and expands it into lessons, activities and assessments, then adapts during the session to the learner's profile. The repository lists three named use cases: course creators handing over a lesson framework, enterprise training teams feeding in content once for role-specific paths, and educators supplying a syllabus for coaching content plus a Q&A assistant. The project is developed by the AI-Shifu Team together with the Research Center of Intelligent Software Engineering at Harbin Institute of Technology, and it is licensed Apache-2.0. If your teaching material is already fully scripted and you do not want an agent improvising around it, the premise of this tool works against you.
How the Pieces Fit: Backend, Cook Web, MySQL, Optional Redis
The deployment material shows two container images: aishifu/ai-shifu-api and aishifu/ai-shifu-cook-web. Cook Web is described as both the learner interface and the authoring console, reachable on port 8080 once the stack is up. The backend holds the session logic and reads its configuration from environment variables. SQLALCHEMY_DATABASE_URI defaults to the MySQL service bundled in the Compose file, so the zero-config path assumes a local database container rather than an external one. Redis is optional: REDIS_HOST is documented as enabling caching and locks, and leaving it empty disables it. That is a real architectural choice worth noting, because a deployment without Redis runs without whatever coordination the locks provide, and the README does not state which operations depend on them. Internationalization is shared rather than duplicated: translation files live in src/i18n/<locale>/**/*.json and are consumed by both the backend and Cook Web, with conventions and CI checks documented in docs/i18n.md. The roadmap lists a writing agent for script generation, a knowledge base, and speech input and output as unchecked items, so none of those three should be assumed present.
Getting It Running: Docker Compose and the One Required Edit
The README gives a quick start that assumes Docker and Docker Compose are already installed. You clone the repository, change into the docker directory, copy .env.example.full to .env, edit the file to set at least one LLM API key, and run docker compose -f docker-compose.latest.yml up -d. The documented key variables include OPENAI_API_KEY, ERNIE_API_KEY and GLM_API_KEY. Everything else in the template has a working default for the Docker path, which is why the README calls this zero config apart from the key. Three defaults deserve attention before anything is exposed to the internet. SECRET_KEY ships with a demo value and should be replaced with output from python -c "import secrets; print(secrets.token_urlsafe(32))". UNIVERSAL_VERIFICATION_CODE defaults to 1024 and is described as a test code to remove or empty in production. And the first verified user is automatically promoted to Admin and Creator, with the bundled demo course assigned to that account. You log in with any phone number and the universal code, then open http://localhost:8080. For source-level work there is ./dev_in_docker.sh, which builds the backend and frontend images from your local tree and launches docker-compose.dev.yml with hot reload and bind mounts, so you do not need Python or Node installed on the host.
Latest Versus Pinned Compose Files
The repository ships two Compose files with different guarantees. docker-compose.latest.yml tracks the :latest tags for aishifu/ai-shifu-api and aishifu/ai-shifu-cook-web, so a restart can pull a different build than the one you tested. docker-compose.yml pins each image to a specific release tag, and the README recommends it for reproducible deployments, staging or production mirrors, and CI. This is the single most consequential operational decision in the project, and it is easy to get wrong because the quick start uses the latest file. If you follow the quick start on a server and later re-run it, you have no record of which build produced your current state. The release cadence visible in the repository is frequent: v2.3.1, v2.3.0 and v2.2.12 all landed within roughly three weeks of each other. A cadence that tight is fine for the latest-tracking file and awkward for anyone who pinned a tag and now wants the next one, because each upgrade means editing the tag and re-running the stack. There is no documented migration procedure in the supplied material, so treat schema changes between tags as something you verify yourself rather than something the README promises.
Where It Falls Short: Locale Coverage, Login Assumptions, Optional Redis
The frontend language list exposes only en-US and zh-CN. A training team operating in any other language will be working against the interface, even though the i18n files themselves are structured per locale under src/i18n. The login flow is the second constraint. Authenticating with any phone number plus a universal verification code is a demo convenience, and the README says so directly, but the first-user-becomes-admin rule means the security of a fresh instance rests on whoever registers first. On a reachable host, that is a race. Third, Redis being optional is presented as a simplification, yet the README also says Redis provides caching and locks. Without it you are running a configuration the documentation does not characterize in terms of behaviour under concurrent sessions. Finally, the roadmap items are unchecked. If your reason for evaluating AI-Shifu is the knowledge base or speech input and output, those are stated intentions, not features you can plan a course around today.
Text-to-Speech Configuration and the Provider Choice
TTS is configured through environment variables rather than through the UI alone. For Volcengine HTTP v1/tts you set VOLCENGINE_TTS_APP_KEY (the AppID), VOLCENGINE_TTS_ACCESS_KEY (the token used in an Authorization: Bearer;{token} header) and VOLCENGINE_TTS_CLUSTER_ID, which defaults to volcano_tts. After that, you select the provider name volcengine_http in Shifu settings and pick a voice and model. The README says multiple TTS providers are supported but only documents this one in the supplied material, so the exact set of alternatives is not something I can confirm from what is here. Note the two-step nature of the setup: environment variables make the provider available, and a settings selection makes it active for a given Shifu. If you skip the second step, the credentials sit unused. Voice selection also implies per-course decisions rather than a single global setting, which matters if you run many courses and want consistent audio.
How It Compares to Wiring an LLM Into an Existing LMS
The obvious alternative is not another teaching agent but the general-purpose route: take an existing learning management system and connect a chat model to it through its plugin or API surface. The difference in approach is where the teaching structure lives. With an LMS plus a model, the course structure stays in the LMS and the model answers questions inside it; you own the prompt design, the learner-profile handling and the assessment loop yourself. AI-Shifu moves that structure into the agent: the authored framework is the input, and the expansion into lessons, activities and assessments is the product. That is a genuine trade. You get the personalization loop without building it, and you give up the ability to see exactly how a given lesson was generated, since the expansion happens at authoring time. The other alternative is the hosted platform at ai-shifu.com, which the README describes as an education platform powered by AI-Shifu with courses developed by human experts. Self-hosting gives you the data and the configuration; the hosted route gives you courses you did not have to build. Which one fits depends on whether your bottleneck is infrastructure or content.
Maintenance, Licensing and What to Check Before You Commit
The licence is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant, with the usual requirement to retain notices and state changes. That is a permissive terms set, and it is not legal advice; if you are embedding AI-Shifu in a product, have counsel read the licence text rather than this paragraph. Maintenance cost has three visible components. First, the release cadence is fast enough that pinning a tag means periodic manual upgrades. Second, the stack depends on external LLM providers, so your operating cost tracks token usage and your availability tracks theirs; the README does not describe fallback behaviour when a provider key is missing or a provider is down. Third, the i18n setup adds a small ongoing obligation, since translations are shared between backend and Cook Web under src/i18n and there are CI checks documented in docs/i18n.md, meaning a locale change touches both consumers. The practical first step is to run the stack once with docker-compose.yml rather than the latest file, replace SECRET_KEY, empty UNIVERSAL_VERIFICATION_CODE, and confirm which LLM key you actually intend to fund before opening the port to anyone else.
Editorial conclusion
Adopt AI-Shifu if you are a course creator or training team willing to run Docker Compose, set an LLM API key and treat the first verified user as the administrator of a single-instance deployment. Do not adopt it if you need more than English and Simplified Chinese in the interface, or if you cannot accept that the universal verification code 1024 is the default login path for demos. Before committing, verify three things: that your chosen LLM provider key is one of the supported variables in .env.example.full, that you have replaced SECRET_KEY with output from python -c "import secrets; print(secrets.token_urlsafe(32))", and that docker-compose.yml rather than docker-compose.latest.yml is what your deployment pipeline pulls, since only the former pins image tags.
Community notes