🐙 Because Two Hands Just Aren't Enough

---

Gemini berkata

🐙 Meet Octopus AI: Because Two Hands Just Aren't Enough

Let's be honest: being a human is exhausting. You only have two arms, one brain, and a desperate, daily need for caffeine. How are you supposed to handle a never-ending to-do list with hardware like that?

Enter Octopus AI.

The Philosophy (Why an Octopus?)

We looked at the animal kingdom for the ultimate productivity guru and found the undisputed multitasking ninja of the sea. Why? Because octopuses are freakishly smart and boast eight highly capable arms.

They can open child-proof jars from the inside, solve puzzles, and juggle multiple tasks without breaking a sweat (mostly because they live underwater, but you get the point). We took that big-brained, multi-limbed brilliance and turned it into an AI tool designed to do your heavy lifting.

What Can the Tentacles Do for You?

🦾 Eight-Armed Multitasking: While your clumsy human hands are still typing a single sentence, Octopus AI is already crunching data, drafting emails, organizing your schedule, and virtually high-fiving itself.

🧠 Escape-Artist Intelligence: Got a problem that feels like you're stuck in a locked box? Octopus AI uses its massive, squishy digital brain to squeeze through complex problems and find elegant solutions.

🔄 Total Flexibility: It adapts to your workflow seamlessly. No rigid bones, no friction—just smooth, intelligent automation wrapping around your daily tasks.

🧹 100% Mess-Free: All the genius of a cephalopod, with absolutely zero ink squirted on your nice clean desk when it gets surprised.

Stop drowning in a sea of tabs and endless tasks. Let Octopus AI wrap its virtual tentacles around your workload, so you can go back to doing what humans do best: taking naps and drinking coffee. ☕

---

🏗️ Architecture

graph TB
    subgraph Frontend["🎨 Frontend (HTML/CSS/JS)"]
        UI[Chat Interface]
        Settings[Settings Panel]
    end

    subgraph Backend["⚙️ FastAPI Backend"]
        Agent[🐙 Agent Engine<br/>plan · act · reflect]
        Config[Config Manager]
        Memory[Memory + Vector RAG]
    end

    subgraph LLM["🧠 LLM Providers"]
        OpenAI[OpenAI<br/>GPT-4o / GPT-4o-mini]
        Anthropic[Anthropic<br/>Claude Sonnet 4]
        Gemini[Google Gemini<br/>Gemini 3 Flash]
        Ollama[Ollama<br/>native tool-calling]
        Local[Local OpenAI-compat<br/>LM Studio / vLLM]
    end

    subgraph Tools["🦑 Tentacle Tools"]
        Shell[🐚 Shell]
        FileOps[📁 File Ops]
        WebBrowse[🌐 Web Browse]
        CodeRun[💻 Code Runner]
        Search[🔍 Web Search]
        Image[🎨 Image Gen]
        Plan[🗺️ Plan]
        Delegate[🤝 Delegate]
    end

    UI -- WebSocket --> Agent
    Settings -- REST API --> Config
    Agent --> LLM
    Agent --> Tools
    Agent --> Memory

Loading

---

🦑 Features

🔧 Eight Powerful Tentacles

Tentacle	Capability	Description
🐚	Shell Commands	Execute system commands with real-time output streaming
📁	File Operations	Read, write, edit, list, and search files & directories
🌐	Web Browse	Navigate, click, type, and read JS-rendered pages (Playwright)
💻	Code Execution	Run Python in a sandboxed, resource-limited subprocess
🔍	Web Search	Search the internet via DuckDuckGo
🎨	Image Generation	Create images from text (DALL·E)
🗺️	Task Planning	Maintain a live step-by-step todo checklist (streamed to the UI)
🤝	Sub-agent Delegate	Spawn focused, tool-capable sub-agents for isolated sub-tasks

🧠 Agentic Engine

• Plan → act → observe → adapt loop with parallel tool calls (swarm), self-healing retries, and result verification.
• Universal tool-calling — native function-calling on OpenAI/Anthropic/Gemini/Ollama/local, plus a prompt-based emulation fallback so even small local models can use tools. Pick the behavior with Tool Mode (auto / native / emulated / off).
• Agent Activity panel showing the live plan and a tentacle timeline, plus an in-header model switcher.

🧠 Multi-Provider LLM Support

Switch between AI providers on the fly — no restart needed:

Provider	Models	Authentication
OpenAI	GPT-4o, GPT-4o-mini, GPT-4-Turbo	API Key
Anthropic	Claude Sonnet 4, Claude 3.5 Haiku, Claude 3 Opus	API Key
Google Gemini	Gemini 3 Flash, Gemini 2.5 Pro/Flash	API Key or Google Sign-In
Ollama	Llama 3.2, Mistral, Code Llama + any local model — now with native tool-calling	Local (free!)
Local (OpenAI-compatible)	LM Studio · llama.cpp · vLLM · text-generation-webui (set a base_url)	Local (free!)

🎨 Premium Dark-Ocean GUI

• Glassmorphism design with deep-ocean dark theme + light mode
• Animated octopus welcome screen with CSS tentacle animation
• Real-time streaming chat with rich Markdown (tables, task lists, sanitized HTML) via marked + DOMPurify
• Agent Activity panel — watch the live plan checklist and tentacle timeline as the agent works
• In-header model switcher with live discovery of installed Ollama / local models
• Settings panel — provider, model, tool mode, temperature, local runtimes, tentacle permissions
• Responsive design optimized for desktop & mobile
• Google Sign-In for seamless Gemini integration

💾 Persistent Memory

• Conversations automatically saved to disk as JSON
• Auto-generated conversation titles
• Full-text searchable conversation history
• Configurable context window (up to 50 messages)

🛡️ Security & Sandboxing (v2.1+)

• Path Isolation: All File and Shell interactions are securely jailed strictly to the data/workspace directory.
• Network Containment: Python subprocess environments are spawned using Linux unshare -rn to sever network access completely and neutralize code-based data extraction.
• Robust Prompt Armor: Extracted texts from DuckDuckGo queries and Web navigations are structurally isolated within XML wrappers (like <untrusted> or <external_content>), effectively stripping them of instruct-override privileges and preventing Prompt Injections.
• Local IP Anchoring: To harden the backend against unauthenticated external hijacking, Octopus utilizes a strict LocalhostRestrictionMiddleware layer blocking all non-local connections.

---

📚 Documentation

Full documentation lives in docs/:

For Users	For Developers
User Guide — install, run, UI tour, usage	Architecture — design & request lifecycle
Providers & Models — cloud + local	Code Structure — file-by-file map
Configuration — every setting	Agent Engine — the plan→act loop
Security — sandbox & threat model	Tools Reference — tentacles + how to add one
	API Reference — REST + WebSocket
	Development Guide — setup, testing, extending

---

🚀 Installation

Prerequisites

Requirement	Version
Python	3.10 or higher
pip	Latest recommended
API Key	At least one (OpenAI / Anthropic / Gemini) — or Ollama for free local models

Quick Start

# 1. Clone the repository
git clone https://github.com/Masriyan/Octopus-Ai.git
cd Octopus-Ai

# 2. Make the start script executable
chmod +x start.sh

# 3. Launch everything (auto-installs deps, starts backend + frontend)
./start.sh

Then open http://localhost:5500 in your browser. 🎉

Manual Setup

If you prefer to set things up manually:

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r backend/requirements.txt

# Copy environment config
cp .env.example .env
# Edit .env and add your API key(s)

# Start the backend
cd backend
python3 -m uvicorn main:app --host 0.0.0.0 --port 8000 --reload &

# Start the frontend (in another terminal)
cd frontend
python3 -m http.server 5500

Configure API Keys

1. Open http://localhost:5500
2. Click the ⚙️ Settings button in the sidebar
3. Select your preferred LLM provider
4. Enter your API key and click Save
5. Start chatting! 🐙

Using Ollama (Free / Local)

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model
ollama pull llama3.2

# In Octopus AI settings → select "Ollama" as provider

---

📖 Usage

Basic Chat

Simply type your message and Octopus AI will respond. It automatically detects when tools would be helpful and uses them proactively.

Capability Quick-Start Cards

The welcome screen features interactive cards that demonstrate each tentacle:

Card	Example Prompt
🐚 Shell	"List all files in my home directory"
📁 Files	"Read and summarize the README.md in the current project"
🔍 Search	"Search the web for the latest AI news"
💻 Code	"Write a Python script to calculate Fibonacci numbers and run it"
🌐 Web	"Fetch and summarize the contents of https://news.ycombinator.com"
🎨 Image	"Generate an image of a cyberpunk octopus in neon lights"
🗺️ Plan	"Plan and build a small CLI to-do app, then implement it"
🦑 Multi	"Research X, delegate the analysis, and summarize your findings"

Settings & Configuration

Setting	Description
LLM Provider	Switch between OpenAI, Anthropic, Gemini, Ollama, or Local
Model	Choose the model (local/Ollama models are auto-discovered)
Tool Mode	How tools are driven: auto / native / emulated / off
Temperature	Control response creativity (0.0 = focused, 1.0 = creative)
Tentacle Permissions	Enable/disable individual tools (incl. Plan & Delegate)
Local Runtimes	Ollama & OpenAI-compatible base URLs / model / key
API Keys	Securely save provider API keys (stored in .env, not config)
Google Sign-In	Authenticate with Google for Gemini access

WebSocket Streaming

Octopus AI uses WebSocket connections for real-time, token-by-token streaming — no polling, no delays.

---

📁 Project Structure

Octopus-Ai/
├── backend/
│   ├── main.py              # FastAPI server + WebSocket endpoints
│   ├── agent.py             # Core agent engine (plan/act/reflect + emulation)
│   ├── llm_providers.py     # OpenAI / Anthropic / Gemini / Ollama / Local
│   ├── config.py            # Configuration manager
│   ├── memory.py            # Conversation persistence (JSON)
│   ├── vector_memory.py     # Long-term RAG (Qdrant + embeddings)
│   ├── requirements.txt     # Python dependencies
│   ├── tests/               # Pytest suite
│   └── tools/
│       ├── __init__.py      # Tool registry & schema builder
│       ├── shell_tool.py    # 🐚 Shell command execution
│       ├── file_tool.py     # 📁 File system operations
│       ├── web_tool.py      # 🌐 Web browse (Playwright)
│       ├── code_tool.py     # 💻 Python code execution
│       ├── search_tool.py   # 🔍 DuckDuckGo web search
│       ├── image_tool.py    # 🎨 Image generation (DALL·E)
│       ├── plan_tool.py     # 🗺️ Live task planning
│       └── delegate_tool.py # 🤝 Sub-agent delegation
├── frontend/
│   ├── index.html           # Main application page
│   ├── css/main.css         # Deep-ocean dark theme
│   └── js/app.js            # Frontend logic & WebSocket client
├── data/                    # Created at runtime (git-ignored)
│   ├── config.json          # User preferences (no secrets)
│   ├── memory/              # Saved conversations
│   ├── vector_db/           # Qdrant vector store
│   └── workspace/           # Sandboxed File/Shell jail
├── docs/
│   └── images/              # Documentation assets
├── .env.example             # Environment variable template
├── .gitignore               # Git ignore rules
├── start.sh                 # One-command launcher
├── CHANGELOG.md             # Release history
├── CONTRIBUTING.md          # Contribution guidelines
├── LICENSE                  # MIT License
└── README.md                # ← You are here

---

🛠️ Development

Backend (FastAPI)

cd backend
python3 -m uvicorn main:app --reload --port 8000

Frontend (Static)

cd frontend
python3 -m http.server 5500

API Documentation

Visit http://localhost:8000/docs for the interactive Swagger UI.

REST API Endpoints

Method	Endpoint	Description
GET	/api/health	Health check (version + tool count)
GET	/api/config	Get configuration (keys masked)
POST	/api/config	Update configuration
POST	/api/config/apikey	Save an API key
GET/POST	/api/config/system-prompt	Get / set custom system prompt
GET	/api/tools	List registered tentacles
GET	/api/conversations	List all conversations
POST	/api/conversations	Create new conversation
GET	/api/conversations/{id}	Get conversation with messages
PATCH	/api/conversations/{id}	Rename conversation
DELETE	/api/conversations/{id}	Delete conversation
GET	/api/conversations/{id}/export	Export as JSON or Markdown
POST	/api/upload	Upload a file for the agent (≤10MB)
GET	/api/models/{provider}	List models (live for ollama/local)
POST	/api/auth/google	Google OAuth sign-in
GET/POST	/api/auth/google/status · /signout	Google session status / sign-out
WS	/ws/chat/{conv_id}	WebSocket for real-time chat + tools

---

🗺️ Roadmap

gantt
    title Octopus AI Development Roadmap
    dateFormat  YYYY-MM
    section Core
    Multi-LLM Providers       :done, 2025-01, 2025-02
    Tool System (5 tentacles) :done, 2025-01, 2025-02
    WebSocket Streaming       :done, 2025-02, 2025-03
    section Enhancements
    Plugin System             :active, 2025-03, 2025-05
    RAG / Document Chat       :2025-04, 2025-06
    Voice Input/Output        :2025-05, 2025-07
    section Infrastructure
    Docker Support            :2025-03, 2025-04
    Auth & Multi-User         :2025-05, 2025-07
    Cloud Deployment          :2025-06, 2025-08

Loading

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-tentacle)
3. Commit your changes (git commit -m 'Add amazing tentacle')
4. Push to the branch (git push origin feature/amazing-tentacle)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

🐙 Philosophy

An octopus has eight arms, each capable of independent action — tasting, gripping, exploring. Octopus AI embodies this: many tools, each specialized, working together to accomplish any task.

---

Made with 🐙 by Masriyan

⭐ Star this repo • 🐛 Report Bug • 💡 Request Feature