AI → Safe Terminal (FastAPI + SPA)

A full-stack app that translates natural-language instructions into safe, sandboxed terminal commands and executes them in a restricted environment.

• Backend: FastAPI
• Frontend: Single-page app served by FastAPI (HTML/CSS/JS)
• Safety: Strict validator and non-shell executor for whitelisted primitives only

Features

• Strict LLM system prompt to return JSON-only command plans
• Server-side validator blocking absolute paths, traversal, and unsafe flags
• Safe executor using Python stdlib (no shell) inside sandbox_root/
• Polished UI with translate → confirm → run flow

Project Structure

• backend/app/main.py — FastAPI app and endpoints
• backend/app/llm.py — LLM integration with fallback translator
• backend/app/validator.py — JSON schema/command validation
• backend/app/executor.py — Safe execution of allowed primitives
• backend/app/templates/index.html — Frontend HTML
• backend/app/static/ — Frontend JS/CSS
• backend/sandbox_root/ — Created at runtime for isolated ops

Setup (Windows, PowerShell)

1. Create a virtual environment

py -m venv .venv

2. Activate it

.\.venv\Scripts\Activate

3. Install dependencies

pip install -r backend\requirements.txt

4. (Optional) Configure OpenAI

• Copy .env.example to .env and set OPENAI_API_KEY and OPENAI_MODEL if desired.
• Without an API key, a minimal fallback translator is used.

5. Run the server (from backend/)

uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

6. Open the app

• Visit http://127.0.0.1:8000/

Security Notes

• Executor disallows .., absolute paths, and recursive deletes. Directories must be empty to remove.
• No shell execution; commands are parsed and executed with Python functions.
• UI requires confirmation for ambiguous or destructive actions.

Environment Variables

Create .env (optional):

• OPENAI_API_KEY — API key for your LLM provider (OpenAI-compatible)
• OPENAI_BASE_URL — Base URL for API (defaults to https://api.openai.com/v1)
• OPENAI_MODEL — Model name (defaults to gpt-4o-mini)

Endpoints

• GET / — UI
• GET /api/health — Health check
• POST /api/translate — Body: { instruction } → Returns translation JSON
• POST /api/execute — Body: { commands, start_cwd } → Returns outputs and final CWD

Allowed Primitives

• ls [path], pwd, cd <dir>, mkdir <dir>, touch <file>, cat <file>
• rm <file_or_dir> (dir must be empty)
• mv <src> <dst>, cp <src> <dst> (no directory copy)
• ps, mem
• echo "text" > file

Development

• Code style: simple and readable. No shell=True anywhere.
• Expand the validator/executor carefully when adding new primitives.

License

MIT (add your preferred license).