Monastery
The homelab's vibe coding center for creating and deploying your projects on your infrastructure.
A self-hosted sanctuary for AI-assisted coding. Monastery is a fully self-hosted, browser-based AI coding environment where you prompt local or frontier LLMs to generate, edit, run, debug, and deploy full applications. The harness runs as a standalone service (Docker-first) and connects to LLM backends over the network.
This is an ever changing work in progress.
- I'm piecing this together and implementing as I can test.
Key Features
- Decoupled Architecture: Harness runs independently of LLM servers. Auto-discovery or manual config for local endpoints.
- 100% Self-Hosted: Everything containerized, network-aware, and privacy-focused.
- Lightweight: Harness container <1GB RAM idle; works on low-power nodes.
- Homelab Native: Deploy to Coolify or Dokploy, route through Cloudflare tunnels, back apps with a shared PocketBase, and keep projects in your own git forge.
- OpenAI-Compatible: Works with Ollama, vLLM, llama.cpp, OpenAI, Groq, and more.
- Build & Discuss: Build mode writes and edits files; Discuss mode answers questions and drafts a plan without touching anything — then Build this plan hands it over.
- Live Preview + Undo: the preview reloads as files land, and every AI edit is snapshotted first so one click abandons it.
Quick Start
Prerequisites
- Docker and Docker Compose
- An LLM endpoint (e.g., Ollama, vLLM, or OpenAI API key)
1. Clone and Configure
git clone https://github.com/jherforth/Monastery.git
cd Monastery
cp .env.example .env (optional - you can enter keys in the UI)
Edit .env to configure your LLM endpoint:
# For Ollama on same host (Linux/Mac):
LLM_BASE_URL=http://host.docker.internal:11434
# For Ollama in separate container:
LLM_BASE_URL=http://ollama:11434
# For OpenAI:
LLM_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=sk-...
2. Run with Docker Compose
docker compose up -d
The harness will be available at http://localhost:3091.
3. Connect to Your LLM
- Open the web UI at
http://localhost:3091
- Navigate to Settings → LLM Endpoints
- Add your LLM endpoint or use auto-discovery to find Ollama on your LAN
- Test the connection and start prompting!
Architecture
┌─────────────┐ HTTP + SSE ┌──────────────┐
│ Browser │ ◄──────────► │ Harness │
│ (Web UI) │ │ (Rust) │
└─────────────┘ └──────┬───────┘
│
┌──────────┼──────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌────────┐ ┌─────────┐
│ Ollama │ │ vLLM │ │ OpenAI │
│ (local) │ │(local) │ │(cloud) │
└──────────┘ └────────┘ └─────────┘
Tech Stack
- Backend: Rust (Axum) - lightweight, safe, performant
- Frontend: React + TypeScript with Vite - modern, responsive UI with Monaco editor
- Database: SQLite - embedded, easy backup
- LLM Client: OpenAI-compatible protocol
- Styling: Tailwind CSS with custom Monastery theme
Configuration
| Environment Variable | Description | Default |
|---|
PORT | API server port (in Docker, nginx serves the UI on 3091 and proxies /api to it) | 8080 |
DATA_DIR | Data directory path | ./data |
LOG_LEVEL | Logging level | info |
LLM_BASE_URL | Default LLM endpoint | - |
DISABLE_DISCOVERY | Disable mDNS discovery | false |
API Endpoints
The full route table lives in crates/harness-api/src/main.rs. By area:
| Area | Routes |
|---|
| Health & models | GET /api/health, GET /api/models |
| Chat | POST /api/projects/:id/chat — one turn: streams the reply and applies its file changes (SSE) |
| LLM endpoints | GET/POST /api/endpoints, DELETE /api/endpoints/:id, POST /api/endpoints/:id/test, GET /api/discovery |
| Projects & files | /api/projects, /api/starters, /api/projects/:id/files (+ read, write, dir, upload, move), shell (user-run only), preview/*path |
| Sessions | /api/projects/:project_id/sessions (+ :session_id, messages) |
| Snapshots | /api/projects/:project_id/snapshots (+ checkpoint, restore, diff) |
| Git | /api/git/connections, status, commit-push, pull, push, clone |
| Hosting | /api/hosting/connections, deploy, preview, deployment-log |
Development
Build from Source
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Build
cargo build --release
# Run
cargo run
Run Tests
cargo test
Self-Hosting Wizard
The built-in wizard (History & Ship → Deploy to your homelab) helps you:
- Detect the project's framework and generate a Dockerfile if it has none
- Deploy it to your Coolify or Dokploy instance, redeploying in place on later runs
- Optionally route it through a Cloudflare tunnel and inject a shared PocketBase URL
- Hand a failed build's log back to the chat to fix
Deploying to Coolify? See Coolify Deployment — Requirements & Setup
for the HTTPS-hostname/TLS prerequisites, how updates redeploy in place, and troubleshooting.
Security
- Minimal outbound connectivity by default
- Model output never executes on its own: shell blocks only run when you click Run, without a shell, from an allowlist, with project-relative arguments only
- File APIs refuse paths outside the project before touching disk
- No Docker socket or other host access required
License
AGPL v3 - see LICENSE for details.
Contributing
Contributions welcome! Please read our contributing guidelines before submitting PRs.
Built with intention for the homelab community
With a little (LOT/ALL) of help from my frields - Qwen, Claude, and DeepSeek - For AI by AI
