Skip to content

README.md

Latest commit

 

History

History
118 lines (82 loc) · 2.76 KB

README.md

File metadata and controls

118 lines (82 loc) · 2.76 KB

Arcane Shell

Arcane Shell is a LAN-only browser-based terminal interface for Linux systems. It exposes a real Bash PTY in a secure FastAPI backend and renders it in the browser using xterm.js. This project is designed for single-host usage on a trusted network and includes command protection features, session logging, and an optional AI assistant powered by the OpenAI API.

Arcane Shell v0.1 is the minimal, stable release used for local testing and development.

Features

Terminal

  • Real Bash PTY via Python's pty, os, and select.
  • Fully interactive terminal rendered with xterm.js.
  • Custom shell prompt: ArcaneShell$:
  • Startup banner:
    Welcome to Arcane Shell, Cast your spells Terminal Wizard!
  • Dangerous command protection: Commands such as rm -rf, mkfs, dd, shutdown, and others require confirmation before execution.
  • Supports multiple shells per session (current stable release uses a single shell).

Assistant (ArcaneAgent)

  • Optional AI assistant tab for system help, command explanations, or code samples.
  • Powered by OpenAI’s REST API.
  • User supplies their API key via environment variable.
  • The assistant key is never included in Git and must not be baked into code.

Logging

  • Logs stored under:
    ~/.arcane_shell/sessions/{session_id}/shell1.log
  • Logs include both input and output with timestamps.
  • Basic password redaction prevents sensitive input from being recorded in plain text (coming soon).

Requirements

  • Linux system (tested on Ubuntu 25.x)
  • Python 3.10+
  • A modern browser
  • OpenAI API key (optional, only required for ArcaneAgent)

Installation

Clone the repository:

git clone git@github.com:knightsky-cpu/arcane-shell.git
cd arcane-shell

Create and activate a Python virtual environment:

python3 -m venv .venv
source .venv/bin/activate


Upgrade pip and install dependencies:

python -m pip install --upgrade pip
pip install -r requirements.txt


If you use the ArcaneAgent assistant, export your API key:

export OPENAI_API_KEY="your_api_key_here"

Running Arcane Shell

Start the application:

./arcaneshell.sh


Then open the UI in your browser:

http://127.0.0.1:8765/ui

Project Structure
arcaneshell/
  __init__.py
  main.py
  routes.py
  shell_manager.py
  logging_utils.py
  assistant.py
  models.py
  static/
    index.html
    style.css
    app.js
    xterm.js
    xterm.css
arcaneshell.sh
requirements.txt
.gitignore
LICENSE
README.md

Roadmap

v0.2: WAN access, Cloudflare Zero Trust, splash screen, UI improvements.

v0.3: Custom encryption layers, improved logging security, local model integration.

v0.4: Client-connector (lab model first), remote monitoring expansion.

v1.0: Cross-platform stable release.

License

Arcane Shell is released under the MIT License. See LICENSE for details.