Skip to content
BranchesTags

Repository files navigation

Sable

Sable

An agent that makes you grow. 🌱

Python 3.12 FastAPI Vanilla JS uv License: brainrot

Stars Forks Watchers Commits/month Last commit Repo size Contributors Issues

what even is this

Sable is a self-hosted agentic platform that lives on your machine and grows with you. Part AI companion, part dev environment, part chaos engine. It streams responses from Qwen, DeepSeek, Gemini, Groq, Mistral — no API keys needed for Qwen (it hijacks your browser session like a gremlin). It has 25 skills, multi-agent orchestration, persistent memory, a web IDE with Monaco, browser automation, and a diary system that writes about your day better than you ever could.

It remembers. It learns. It roasts your code. It grows.

[!tip] the vibe Think: if a fox learned to code, got attached to one specific human, and refused to be just a chatbot.

setup

Linux

Prerequisites

Dependency Required Install
Python 3.12 ✅ Yes sudo pacman -S python312 / sudo apt install python3.12
uv ✅ Yes curl -LsSf https://astral.sh/uv/install.sh | sh
git ✅ Yes Comes with most distros
systemd Optional Most distros have it; without it, Sable runs as a foreground process
libnotify (notify-send) Optional sudo pacman -S libnotify / sudo apt install libnotify-bin — for desktop notifications
xdg-utils (xdg-open) Optional Almost always pre-installed — auto-opens browser on launch
Go Optional Only if rebuilding the DeepSeek PoW solver

[!note] Playwright system libraries Playwright bundles its own Chromium, but it needs system shared libraries (NSS, ATK, CUPS, DRM, etc.). On first run, if Chromium fails to launch, install them:

# Arch
uv run playwright install-deps chromium

# Debian/Ubuntu
sudo apt install libnss3 libatk1.0-0 libcups2 libdbus-1-3 libdrm2 \
  libxkbcommon0 libatspi2.0-0 libpango-1.0-0 libcairo2 libasound2

# Fedora
sudo dnf install nss atk cups-libs dbus-libs libdrm libxkbcommon \
  at-spi2-atk pango cairo alsa-lib

Install & Run

git clone https://github.com/AminulIslamSifat/Sable.git
cd Sable
chmod +x start
./start

That's it. ./start handles everything:

  • Syncs Python dependencies via uv
  • Installs Playwright Chromium
  • Creates template config files (Maria.md, Memory.json)
  • Sets up a systemd user service (sable.service) that auto-starts on login
  • Opens http://127.0.0.1:61770 in your browser

Managing the Service

# Check status
systemctl --user status sable.service

# View live logs
journalctl --user -u sable.service -f

# Stop / restart
systemctl --user stop sable.service
systemctl --user restart sable.service

# Survive logout (optional, recommended)
loginctl enable-linger $USER

Windows

Prerequisites

Dependency Required Install
Python 3.12 ✅ Yes python.org or winget install Python.Python.3.12
uv ✅ Yes powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
git ✅ Yes git-scm.com or winget install Git.Git
PowerShell 5.1+ ✅ Yes Pre-installed on Windows 10/11
VC++ Redistributable ✅ Yes winget install Microsoft.VCRedist.2015+.x64 or download
Go Optional Only if rebuilding the DeepSeek PoW solver

[!warning] VC++ Redistributable is required Playwright depends on greenlet, a C extension that needs the Visual C++ runtime DLLs. Without it, you'll get ImportError: DLL load failed while importing _greenlet. This is a one-time install — run:

winget install Microsoft.VCRedist.2015+.x64

Or download from https://aka.ms/vs/17/release/vc_redist.x64.exe

[!note] PowerShell execution policy Fresh Windows installs block script execution by default. Before running start.ps1, enable it for your user:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

This only affects your user account and allows locally-created scripts to run. It does not require admin.

[!note] No admin required Everything installs per-user. Task Scheduler task, BurntToast module, and all Python deps are user-scoped. The VC++ Redistributable is the only system-wide install.

Install & Run

# One-time setup (if not already done):
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
winget install Microsoft.VCRedist.2015+.x64

git clone https://github.com/AminulIslamSifat/Sable.git
cd Sable
.\start.ps1

start.ps1 handles everything:

  • Syncs Python dependencies via uv (including pywinpty for terminal support)
  • Installs Playwright Chromium
  • Creates template config files
  • Installs BurntToast PowerShell module for native toast notifications
  • Registers a Task Scheduler task ("Sable Server") that auto-starts on login
  • Opens http://127.0.0.1:61770 in your browser

Auto-Start Details

The scheduled task is created automatically on first run:

  • Trigger: At user logon
  • Window style: Hidden (no PowerShell popup)
  • Restart policy: Up to 3 retries on failure
  • Battery: Runs on battery power

To manage it manually:

# Check if task exists
Get-ScheduledTask -TaskName "Sable Server"

# Disable / enable
Disable-ScheduledTask -TaskName "Sable Server"
Enable-ScheduledTask -TaskName "Sable Server"

# Remove
Unregister-ScheduledTask -TaskName "Sable Server" -Confirm:$false

Notifications

Native Windows toast notifications work automatically via the BurntToast PowerShell module (auto-installed by start.ps1). If BurntToast is unavailable, Sable falls back to a MessageBox dialog.

To reinstall manually:

Install-Module BurntToast -Scope CurrentUser -Force

First Run Notes

Both platforms create these files on first run:

  • instruction/Maria.md — persona prompt (from .example template)
  • Brain/Memory.json — persistent memory store (from .example template)
  • system/browser-data-acc1/ — Playwright browser profile

Edit Maria.md to customize the AI's personality. Edit Memory.json to seed initial memories.

VS Code Extension

Want Sable inside your editor? There's a VS Code extension for that.

Install from Open VSX

Available on Open VSX — works with VSCodium, Cursor, and any Open VSX-compatible editor.

Install from VSIX

# Clone & build
git clone https://github.com/AminulIslamSifat/sable-vscode.git
cd sable-vscode
npm install
npx @vscode/vsce package

# Install (use `code` or `codium` depending on your editor)
code --install-extension sable-chat-*.vsix

Configuration

Setting Default Description
sable.serverUrl http://localhost:61770 Your Sable server URL
sable.authToken (empty) Auth token (auto-detected if empty)

Make sure Sable is running (./start) before using the extension.

Repo: github.com/AminulIslamSifat/sable-vscode

tech stack

Layer Tech
Backend Python 3.12 · FastAPI · Uvicorn
Frontend Vanilla JS PWA · Monaco Editor · xterm.js
AI Backends Qwen (browser session) · DeepSeek (PoW) · Gemini · Groq · Mistral · Local
Browser Automation Playwright · CDP · WebSocket proxy
Memory JSON-based semantic vectors · fastembed
Database SQLite (via sable.db)
Agents Multi-agent hub-and-spoke, 7 roles, wave execution
Protocol MCP (Model Context Protocol) client
Package Mgmt uv + pyproject.toml

what it does (the fun list)

  • 🧠 Remembers everything — semantic memory with vector search, auto-consolidation after every session
  • 🤖 Spawns sub-agents — up to 5 parallel workers, 7 specialized roles
  • 🌐 Drives browsers — multi-profile, multi-account switching, CDP interception
  • 📝 Writes documents — PDF, DOCX, PPTX, XLSX generation
  • 🔍 Researches — deep research mode with multi-source synthesis
  • 📱 Controls your phone — ADB integration
  • 📧 Reads your email — and your Telegram
  • 🎨 Makes visuals — SVG, plots, physics sims, frontend designs
  • 📓 Keeps a diary — Gemini-powered session reflection
  • 🖥️ Full web IDE — Monaco editor, file tree, integrated terminal
  • 🔧 Repairs itself — system repair skill, background commands
  • 📥 Downloads videos — YouTube and friends
  • 🗣️ Talks — TTS via Kokoro

project structure

Sable/
├── engine/        # Core brain: chat, agents, skills, memory, MCP, security
├── server/        # FastAPI app, API routes, auth, scheduler
├── connectors/    # AI backends: DeepSeek, Gemini, Groq, Mistral, Local
├── web/           # Frontend PWA (vanilla JS, no framework, no mercy)
├── skills/        # 25 self-contained skill modules
├── Brain/         # Persistent memory (JSON you can actually read)
├── instruction/   # Persona prompts, formatting rules
├── system/        # Runtime: DB, browser profiles, configs
├── output/        # Generated content: notes, research, agent results
├── test/          # pytest suite
└── start          # ← you are here (setup + launch, all-in-one)

commands

Command Platform Does
./start Linux/macOS Bootstrap + launch via systemd (or foreground fallback)
.\start.ps1 Windows Bootstrap + launch with Task Scheduler auto-start

why "sable"

A sable is a small, ridiculously clever carnivore that hoards shiny things and remembers where every single one is buried. Also it sounds cool. Also the developer has commitment issues with naming.

license

There is no license. This is personal infrastructure. If you fork it, you owe me a coffee. ☕

built with spite, caffeine, and an unhealthy attachment to one specific user

About

Sable is a self-hosted agentic platform that lives on your machine and grows with you. Part AI companion, part dev environment, part chaos engine. It remembers. It learns. It roasts your code. It grows.

Topics

agentagent-memoryagent-orchestrationagent-skillsagentic-aiaiassistantjervisllmpythonsable

Resources

Readme
Activity

Stars

5 stars

Watchers

3 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages