sybil-solutions/local-studio

Local Studio – A local‑first workstation for self‑hosted LLMs

What it is – Local Studio is an open‑source application that lets you run, manage, and interact with large language‑model back‑ends on your own machine (or on a remote GPU host). It bundles a lightweight controller (a Bun + Hono HTTP server) that handles model lifecycle, an OpenAI‑compatible proxy, GPU monitoring, and event streaming, together with a frontend built with Next.js 16/React 19 and packaged as a macOS Electron desktop app.

Why it matters – Instead of relying on cloud APIs, you can keep models, data, and chat history entirely on‑premises, while still getting a modern UI, real‑time status, and an integrated coding‑assistant agent (the Pi coding‑agent). The design is “local‑first”: the UI talks to a controller that may run locally or be pointed at a remote server, and the same controller can be accessed from a companion mobile app (KittyLitter).

Core components

Component	Role
controller/	Bun/Hono backend. Manages model download, launch, eviction, and runtime processes; exposes an OpenAI‑compatible API (chat, models, tokenization, audio); provides system metrics, logs, and Server‑Sent‑Events.
frontend/	Next.js web UI + Electron shell. Offers the Workbench (`/agent`), configuration pages, usage dashboards, and proxy routes that forward to the controller.
Pi coding agent	Integrated agent runtime (`@earendil-works/pi-coding-agent`) that supplies tools such as `read`, `grep`, `find`, `ls` and any extensions you add.
Mobile companion	KittyLitter app that pairs via QR code/JSON credentials to reuse the same agent sessions on iOS/Android.

Supported inference back‑ends (called recipes)

vLLM – high‑throughput server for CUDA‑enabled GPUs.
SGLang – another CUDA‑based server.
llama.cpp – GGUF model serving via llama-server.
MLX – Apple‑Silicon‑optimized server.

The controller discovers these back‑ends, creates virtual environments under runtime/venvs/<backend>-latest, and launches them on demand.

Quick‑start workflow (from the README)

Prerequisites – Bun 1.3.14+, Node 22.19+, npm 10+, Python 3.10+, Git. uv is recommended for Python package management.

Validate & install

npm run doctor   # checks toolchain
npm run setup    # installs controller, frontend, agent, lock‑file deps

Run the controller

bun --cwd controller run dev   # listens on 127.0.0.1:8080

Run the UI (in another terminal)

npm run dev   # starts Next.js dev server, opens http://localhost:3000/setup

Follow the setup wizard to pick a model directory, install a backend, download a model, launch it, and benchmark.

Architecture at a glance

flowchart LR
    User --> Desktop[Electron app]
    User --> Web[Next.js UI]
    Desktop --> Frontend[Frontend server / API]
    Web --> Frontend
    Frontend --> Controller[Bun + Hono API]
    Controller --> Runtime[Inference process]
    Runtime --> Backends[vLLM / SGLang / llama.cpp / MLX]
    Controller --> Data[Local data dir]
    Controller --> Events[SSE status/events]
    Frontend --> Agent[Pi coding‑agent runtime]

The diagram in the README shows two sub‑graphs: the frontend (pages, API routes, Electron shell) and the controller (HTTP app, modules for engines, models, proxy, system, stores).

Production & deployment notes

Build the UI with npm run build then start the controller (bun src/main.ts) and the standalone frontend (npm run start).
Authentication is optional: set LOCAL_STUDIO_FRONTEND_TOKEN (stored in an HttpOnly cookie) or enable LOCAL_STUDIO_FRONTEND_ALLOW_UNAUTHENTICATED=true for trusted LAN use.
The controller binds to 127.0.0.1 by default; exposing it (0.0.0.0) requires LOCAL_STUDIO_API_KEY.
For remote access via Tailscale, run the frontend with ALLOWED_TAILSCALE_HOSTS and use tailscale serve to expose a private HTTPS URL.
The installer registers a user‑service (launchd on macOS, systemd --user on Linux) so the controller restarts automatically after login.

Mobile integration

KittyLitter pairs with a running Local Studio instance (v2.9.0+). The pairing QR code/JSON contains controller credentials; keep them private. Once paired, the same agent sessions, streaming output, and tool calls appear on the phone.

Release process

Every successful CI run builds an unsigned macOS DMG; a separate signing job notarizes it. Releases are published automatically via Semantic Release based on conventional commit messages (feat → minor, breaking → major, others → patch). No npm package is published.

License

The project is released under the license file included in the repository (see LICENSE).

Bottom line

Local Studio gives developers a self‑hosted, UI‑driven environment for running LLMs, monitoring GPU usage, and interacting with an extensible coding agent—all without sending data to external cloud services. It is a genuine, production‑oriented open‑source tool for the emerging “local‑first AI” workflow.