LinuxPath v6

A local-first Linux command training app with a real Ubuntu terminal, guided lessons, mission validation, and Fibonella, an AI tutor mascot that helps beginners understand what they are typing.

LinuxPath is built for people who want to learn Linux commands safely before touching a VPS, production server, cloud shell, WSL workflow, or DevOps environment.

What You Get

• Real Linux commands in a local Docker Ubuntu sandbox.
• Guided lessons that move from Newbie to Intermediate to Pro.
• Missions that validate real files, folders, logs, and command output.
• Fibonella tutor chat with expression-aware mascot feedback.
• F1 command help and F2 command reference anywhere the terminal is active.
• Local progress, XP, streaks, unlocks, and learning memory.
• Strongly recommended AI provider support through Groq, OpenAI-compatible APIs, or Ollama for deeper command explanations.

Who This Is For

• Beginners who have never used a terminal.
• Windows users who want Linux confidence without breaking their machine.
• Students preparing for servers, cloud, cybersecurity, DevOps, or backend work.
• Intermediate learners who know commands but need structured practice.

LinuxPath is not a public SaaS backend. It is a local learning lab.

How The App Works

Docker runs the whole app locally:

Service	Purpose
sandbox	Ubuntu container where the learner types real commands as user learner.
backend	Node API, WebSocket terminal bridge, mission checks, learning store, AI provider bridge.
frontend	React and TanStack Start user interface.
middleware	Local gateway at http://localhost:3000 for frontend, API, and WebSocket traffic.

Your terminal is not fake. Commands like pwd, ls, cd, mkdir, touch, grep, cat, chmod, ps, and curl run inside the Docker sandbox.

Learning data is stored locally in the linuxpath-learning-data Docker volume. Sandbox files are stored in the linuxpath-sandbox-data Docker volume.

Requirements

Install these first:

Tool	Why You Need It	Link
Git	Clone the repository.	Download Git
Docker Desktop	Run the sandbox, backend, frontend, and gateway.	Download Docker Desktop
Node.js 20+	Optional for local frontend checks outside Docker.	Download Node.js

Windows users should keep Docker Desktop running with Linux containers enabled. Docker Desktop usually uses WSL2 internally; you do not need to open WSL manually.

Quick Start

Clone the repo:

git clone https://github.com/axthithya/LinuxPath.git
cd linuxpathinho

Optional advanced setup: create a local environment file now only if you want preconfigured ports/secrets/providers before first run:

cp .env.example .env

You can skip .env on first run and configure your Groq/OpenAI-compatible/Ollama key later in Settings under AI Provider.

Start the app:

docker compose up -d --build

Open the app:

http://localhost:3000

Check service health:

docker compose ps

Stop the app without deleting learning data:

docker compose down

Delete all local app data and start fresh:

docker compose down -v

Use down -v carefully. It removes the learning and sandbox Docker volumes.

First Learning Flow

1. Open http://localhost:3000.
2. Choose the Newbie track.
3. Start in Lessons to learn commands step by step.
4. Use the Sandbox Terminal to run the command for each step.
5. Move into Missions when you want validation challenges.
6. Open Progress to see XP, rank, track gates, completed lessons, and recent activity.
7. Use Settings to configure AI Provider first (highly recommended), then use reset options only when needed.

New players start in Newbie. Intermediate and Pro unlock through progress instead of being freely selectable from day one.

Tracks And Unlocks

Track	Starts Locked?	Unlock Idea
Newbie	No	Available from first launch.
Intermediate	Yes	Finish Newbie lesson and mission gates, then reach the required rank.
Pro	Yes	Finish Intermediate gates, then reach the required rank.

Each track currently has 15 lessons. The intended flow is:

15 Newbie lessons -> 15 Intermediate lessons -> 15 Pro lessons

Missions and rank also matter, so learners cannot skip straight to harder modes without practice.

Fibonella, F1, And F2

Fibonella is the learning assistant shown across Lab, Lessons, Missions, Progress, and Settings.

Control	What It Does
F1	Ask Fibonella to explain the current terminal line or current lesson context.
F2	Open the command reference overlay.
Fibonella chat box	Ask follow-up questions in normal language.

Fibonella can:

• Explain commands before you run them.
• Explain why a mission may not have cleared.
• Warn about risky commands.
• React to terminal activity with different mascot expressions.
• Use your current lesson, mission, command, and sandbox context.

Fibonella does not:

• Run commands for you.
• Award XP directly.
• Bypass mission validation.
• Disable safety checks.
• Store API keys in browser local storage.

AI Provider Setup

AI Provider is highly recommended and plays a major role in learning quality.

The terminal, lessons, missions, XP, and unlocks still run without AI, but guidance depth is noticeably lower.

For the best LinuxPath experience, open Settings, choose one provider, save, and run a provider test before starting lessons/missions.

Option 1: Groq

Groq is usually the easiest hosted option for fast open model responses.

1. Create or sign in to a Groq account: Groq Console.
2. Open API keys: Groq API Keys.
3. Create a key.
4. In LinuxPath Settings, choose groq.
5. Paste the key into the Groq API key field.
6. Keep the default model or choose another model from the Groq console.
7. Click save, then test.

Environment alternative:

AI_ENABLED=true
AI_PROVIDER=groq
GROQ_API_KEY=your_key_here
GROQ_MODEL=llama-3.3-70b-versatile

Option 2: OpenAI-Compatible API

Use this for OpenAI, xAI/Grok, OpenRouter, local gateways, or any provider that exposes an OpenAI-compatible chat API.

Useful links:

• OpenAI API keys
• OpenAI quickstart
• xAI console for Grok models
• OpenRouter keys

In Settings choose openai-compatible, then provide:

Field	Example
API key	Provider key from OpenAI, xAI, OpenRouter, or another service.
Base URL	https://api.openai.com/v1 for OpenAI, or the provider's documented base URL.
Model	A chat model name supported by that provider.

Environment alternative:

AI_ENABLED=true
AI_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_API_KEY=your_key_here
OPENAI_COMPATIBLE_BASE_URL=https://api.openai.com/v1
OPENAI_COMPATIBLE_MODEL=your_model_here

For xAI/Grok, use the xAI console values and the xAI OpenAI-compatible base URL from their docs.

Option 3: Ollama

Ollama runs models locally on your computer.

1. Install Ollama: Download Ollama.
2. Start Ollama.
3. Pull a model:

ollama pull llama3.1

4. In LinuxPath Settings, choose ollama.
5. Use this base URL from Docker:

http://host.docker.internal:11434

6. Use the model name you pulled, for example:

llama3.1

Environment alternative:

AI_ENABLED=true
AI_PROVIDER=ollama
OLLAMA_BASE_URL=http://host.docker.internal:11434
OLLAMA_MODEL=llama3.1

Core Pages

Page	Purpose
Lab	Free practice terminal with Fibonella beside it.
Missions	Challenge queue with automatic backend validation.
Lessons	Guided lesson flow with command steps and sandbox practice.
Progress	Track progress, unlock gates, rank, XP, roadmap, and recent activity.
Settings	AI provider setup, track switching after unlocks, sandbox reset, learning reset.

Reset Options

Reset Sandbox

Use this when the sandbox files are messy and you want a clean practice folder again.

It resets /home/learner inside the sandbox and keeps:

• XP
• lessons
• missions
• rank
• Fibonella memory
• AI settings

Clear Learning Database

Use this when you want to restart the learning journey.

It clears:

• selected track
• onboarding state
• XP and rank
• lesson progress
• mission progress
• learning memory

It does not reset sandbox files or AI provider settings.

Full Docker Wipe

docker compose down -v

This removes both learning data and sandbox files.

Project Structure

linuxpathinho/
  backend/               Node API, terminal bridge, mission validation, learning store
  frontend/              React/TanStack Start UI
  middleware/            Local gateway for app, API, and WebSocket routes
  sandbox/               Ubuntu sandbox image and starter files
  docker-compose.yml     Local multi-service app definition
  .env.example           Environment template
  README.md              Beginner setup and project guide

Important frontend files:

frontend/src/routes/lessons.tsx       Lesson page
frontend/src/routes/missions.tsx      Mission page
frontend/src/routes/progress.tsx      Progress dashboard
frontend/src/routes/settings.tsx      Settings page
frontend/src/data/lessons.ts          Frontend lesson metadata
frontend/src/data/missions.ts         Frontend mission packs
frontend/src/data/trackUnlocks.ts     Track unlock rules
frontend/src/data/fibonellaExpressions.ts  Mascot expression mapping
frontend/src/assets/fibonella/        Fibonella expression images

Important backend files:

backend/data/lessons.json             Backend lesson database
backend/services/learningStore.js     Local learning persistence
backend/services/monitorService.js    Command monitoring and learning events
backend/routes/                       API routes
sandbox/starter-files/                Files copied into a fresh sandbox

Changing Lessons Or Missions

When adding or changing lesson content, update both the frontend and backend lesson sources if the change affects UI display and backend progress data:

frontend/src/data/lessons.ts
backend/data/lessons.json

When adding mission content, check:

frontend/src/data/missions.ts
backend/services or backend/routes mission validation logic
sandbox/starter-files if the mission needs starter files

When adding mascot expressions:

1. Put the image in frontend/src/assets/fibonella/.
2. Import it in frontend/src/data/fibonellaExpressions.ts.
3. Add the expression to the FibonellaExpression type.
4. Map the expression in the UI decision logic.

Development Commands

Frontend build:

npm --prefix frontend run build

Frontend type check:

frontend/node_modules/.bin/tsc -p frontend/tsconfig.json --noEmit

Start or rebuild Docker services:

docker compose up -d --build

Check logs:

docker compose logs --tail 80 backend
docker compose logs --tail 80 frontend

Check containers:

docker compose ps

Troubleshooting

Docker Desktop is not running

Start Docker Desktop and wait until it says the engine is running. Then run:

docker compose up -d --build

Port 3000 is already used

Set another app port in .env:

APP_PORT=3001

Then restart:

docker compose up -d

Open http://localhost:3001.

Terminal stays disconnected

Use the middleware URL, not the frontend container URL:

http://localhost:3000

Then check:

docker compose ps
docker compose logs --tail 80 backend

Progress disappeared

Check whether you ran:

docker compose down -v

That command deletes Docker volumes. Without -v, progress should stay.

Fibonella says AI is not configured

Open Settings, choose a provider, save, and test. The app still works without AI, but F1 explanations and chat need a configured provider.

Ollama test fails

Make sure Ollama is running on the host and that Settings uses:

http://host.docker.internal:11434

Also confirm the model exists:

ollama list

Safety Notes

Do not expose this backend to the public internet. It mounts the Docker socket read-only so it can open terminals and validate missions inside the local sandbox. That is acceptable for a local learning app and not acceptable as a hosted public service without a different security design.

The sandbox is designed for learning, not for storing important files.

Project Motive

Linux commands are intimidating when the first mistake feels expensive. LinuxPath gives beginners a real terminal where mistakes are expected, visible, and recoverable. The goal is confidence: understand the command, run it safely, see the result, and build the habit one lesson at a time.

Future versions can add more lessons, richer missions, more command families, and deeper Fibonella coaching. The current goal is a clean, local, beginner-friendly foundation.