LiveAgent

Your Local-First AI Agent Desktop
Multi-model access · Local tool execution · MCP & Skills ecosystem · Remote Gateway

English | 简体中文

Core Features • Download & Deployment • FAQ • Docs

For all things AI, head to LINUX DO! Wishing the community ever greater success~

	PackyCode is a reliable, efficient, and professional API relay service provider, offering relay services for Claude Code, Codex, Gemini, Chinese domestic models, and more — a long-established, top-tier relay. The vast majority of the model resources used to develop this software were provided by PackyCode — thank you, Laonong! Register here to get started!
	Right Code provides stable relay services for Claude Code, Codex, Gemini, Chinese domestic models, and more. Invoices are available upon top-up, and enterprise and team users receive dedicated one-on-one support. The remaining model resources used to develop this software were provided by RightCode — thanks to the RC site owner and the support team! Register here to get started!
	Cubence is a reliable and efficient API relay service provider, offering relay services for Claude Code, Codex, Gemini, and more, with pay-as-you-go billing. Thanks to Cubence for supporting this project! Register here to get started!

Scan the QR code to join our QQ group and help drive LiveAgent development!
(Why a QQ group? It just packs a few more features than a WeChat group~)

-macOS-aarch64.dmg` - Intel: `LiveAgent--macOS-x64.dmg` > The installer is signed and notarized by Apple — no manual security override is needed on first launch. ### Windows Pick an installation method from [Releases](https://github.com/Stack-Cairn/LiveAgent/releases/latest): | Method | File | Best for | |---|---|---| | Setup wizard | `LiveAgent--Windows-x64-Setup.exe` | Most users | | MSI package | `LiveAgent--Windows-x64.msi` | Enterprise distribution / silent install | | Portable | `LiveAgent--Windows-x64-portable.zip` | No install — unzip and run | ### Linux Choose by distribution from [Releases](https://github.com/Stack-Cairn/LiveAgent/releases/latest): | Format | Distributions | Install | |---|---|---| | AppImage | Any distribution | `chmod +x`, then run directly | | DEB | Debian / Ubuntu family | `sudo dpkg -i LiveAgent--Linux-x86_64.deb` | | RPM | Fedora / openSUSE family | `sudo rpm -i LiveAgent--Linux-x86_64.rpm` | ### Need Remote Access? Deploy the Gateway The desktop app works out of the box and depends on no server. Deploy the Gateway only if you want to **control your local agent from a browser**. **Note: when deployed behind an Nginx reverse proxy, set the Gateway address on the Settings → Remote page to the HTTPS URL and use port 443.** ```bash # Pull the image (built by GitHub Actions, multi-arch: amd64 / arm64) docker pull ghcr.io/stack-cairn/liveagent-gateway:latest # Run in the background (HTTP/WebSocket → host 3000) docker run -d \ --name liveagent-gateway \ --restart unless-stopped \ -p 3000:8080 \ -v liveagent-gateway-data:/var/lib/liveagent \ -e LIVEAGENT_GATEWAY_TOKEN=your-token \ ghcr.io/stack-cairn/liveagent-gateway:latest ``` The named volume persists the Gateway database and independently issued Agent tokens across container upgrades. **One-command upgrade to the latest version** — pull the new image → remove the old container → recreate it with the same arguments (if you changed the port mappings or token, adjust the arguments below accordingly): ```bash docker pull ghcr.io/stack-cairn/liveagent-gateway:latest \ && docker rm -f liveagent-gateway \ && docker run -d \ --name liveagent-gateway \ --restart unless-stopped \ -p 3000:8080 \ -v liveagent-gateway-data:/var/lib/liveagent \ -e LIVEAGENT_GATEWAY_TOKEN=your-token \ ghcr.io/stack-cairn/liveagent-gateway:latest \ && docker image prune -f ```

Nginx reverse proxy configuration — reference for custom domains / TLS

> Since protocol v2, all traffic — the WebUI, the HTTP API, and the WebSocket links of both the browser and the desktop app — goes through the single HTTP port (default 3000). > > WebSocket upgrades happen on several paths (`/ws/v2`, `/ws/v2/agent`, `/ws/v2/terminal`, and tunnels under `/t/`), so the simplest correct setup enables the upgrade on the whole vhost: ```nginx # WebUI SPA/static/API + every WebSocket link (browser and desktop) location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; # WebSocket upgrade proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; # Required: the Gateway's same-origin check compares the browser's # Origin header against X-Forwarded-Proto + Host proxy_set_header Host $host; proxy_set_header Authorization $http_authorization; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # The Gateway pings every WebSocket connection every 15s, # so a generous-but-finite timeout is enough proxy_read_timeout 300s; proxy_send_timeout 300s; proxy_buffering off; } ``` > The upstream port maps to the host port from the `docker run` above: HTTP/WebSocket 3000 (inside the container, HTTP actually listens on `PORT=8080`). The server block needs `listen 443 ssl;` and a `client_max_body_size` large enough for attachment uploads (e.g. `100m`).

### Build from Source Expand the Development Guide below for the full set of Make commands. 

Architecture Overview — diagram & tech stack

``` ┌──────────────────────────────────────────────────────────────┐ │ Browser WebUI │ │ React + Vite + WebSocket + Gateway API │ └────────────────────────────┬─────────────────────────────────┘ │ WebSocket / HTTP ┌────────────────────────────▼─────────────────────────────────┐ │ Agent Gateway │ │ Go · WebSocket · HTTP · Session Manager · Event Store │ │ (Railway / Docker / self-hosted) │ └────────────────────────────┬─────────────────────────────────┘ │ WebSocket v2 (bidirectional stream) ┌────────────────────────────▼─────────────────────────────────┐ │ Agent GUI │ │ Tauri 2 · React 19 · Rust │ ├──────────┬────────────┬───────────┬────────────┬─────────────┤ │ Models │ Runtime │ Tools │ Skills │ Memory/Cron │ │ pi-ai │ multi-turn │ FS/Bash/ │ progressive│ SQLite+MD │ │ + Codex │ + SubAgent │ MCP bridge│ + Hub │ FTS index │ └──────────┴────────────┴───────────┴────────────┴─────────────┘ ``` **Tech Stack** | Component | Technology | |---|---| | **Agent GUI** · Framework | Tauri 2 + React 19 + TypeScript 6 | | **Agent GUI** · Build | Vite 8 + pnpm | | **Agent GUI** · Styling | Tailwind CSS 4 + Radix UI | | **Agent GUI** · Rendering | streamdown + KaTeX + Mermaid + Monaco Editor | | **Agent GUI** · Backend | Rust + Tokio + SQLite (rusqlite) + WebSocket (tokio-tungstenite) | | **Agent GUI** · LLM | @earendil-works/pi-ai · @earendil-works/pi-agent-core | | **Gateway** · Language | Go 1.25 | | **Gateway** · Protocols | WebSocket + Protobuf + HTTP | | **Gateway** · Web UI | React + Vite + Tailwind CSS (embedded) | | **Gateway** · Deployment | Docker multi-stage · Railway CI/CD |

Development Guide — common Make commands (run make help for the full list)

| Command | Description | |---|---| | `make dev` | Start Tauri development with Session Workbench enabled (`DEV_SESSION_WORKBENCH=0` restores the legacy single-conversation layout) | | `make build` | Build the desktop app | | `make dev-gateway` | Start the Gateway dev server | | `make dev-webui` | Start the WebUI dev server | | `make gateway-build` | Build the Gateway binary | | `make gateway-docker-build` | Build the Docker image | | `make gateway-docker-smoke` | Build + health check | | `make desktop-build-macos-release` | macOS signed release build | | `make build-linux` | Linux amd64 gateway | | `make build-linux-arm` | Linux arm64 gateway | | `make proto` | Regenerate Protobuf code | | `make clean` | Clean build artifacts |

Project Structure — directory tree

``` LiveAgent/ ├── package.json # pnpm workspace commands ├── pnpm-lock.yaml # Unified frontend dependency lock ├── crates/ │ ├── agent-ui/ # Shared GUI/WebUI React source │ │ └── src/ # Components, domain models, settings shell │ │ │ ├── agent-gui/ # Desktop client │ │ ├── src/ # React frontend │ │ │ ├── components/ # UI components │ │ │ ├── lib/ # Core logic (chat, tools, skills, memory) │ │ │ ├── pages/ # Pages (Chat, Settings) │ │ │ ├── i18n/ # Internationalization │ │ │ └── prompt/ # System prompt templates │ │ └── src-tauri/ # Rust backend (Tauri) │ │ │ └── agent-gateway/ # Go gateway service │ ├── cmd/gateway/ # Entry point │ ├── internal/ # Core implementation │ ├── proto/v2/ # Protobuf definitions │ └── web/ # Embedded WebUI │ ├── docs/ # Project docs │ ├── architecture/ # Architecture design │ ├── features/ # Feature guides │ └── operations/ # Operations & deployment │ ├── scripts/release/ # Release automation ├── .github/workflows/ # CI/CD (CI + Desktop Release + Gateway Docker) ├── Dockerfile # Gateway container image ├── Makefile # Build commands └── Cargo.toml # Rust workspace ```

--- ## FAQ

Does my API key ever leave my machine?

No. Keys are stored locally on the desktop side only. The Gateway is a pure protocol relay — it never accesses the file system and never stores any credentials.

Do I have to deploy the Gateway?

No. The desktop client works standalone with all local capabilities; deploy the Gateway only when you need browser-based remote access to your local agent.

Which models are supported?

Claude (Anthropic), Codex (OpenAI), and Gemini protocols are built in, plus custom Base URL support for any compatible third-party service.

Will long conversations / disconnects lose context?

No. The desktop app persists the full history with Segment + Summary Checkpoints; the Gateway replays short disconnects through a bounded seq window and converges automatically after reconnecting.

--- ## Contributing Issues and pull requests are welcome! See the [Development Guide](docs/operations/development.md) for setting up a dev environment. Before submitting a PR, make sure all of the following checks pass (they match the CI gates): Install frontend dependencies once from the repository root with `pnpm install --frozen-lockfile`. **Desktop client** 1. Type check & build pass: `pnpm build:gui` 2. Lint passes: `pnpm lint:ui && pnpm lint:gui` 3. Frontend unit tests pass: `pnpm test:gui` (also run `pnpm --filter liveagent test:release` when touching release scripts) 4. Rust backend check passes: `cargo check --manifest-path crates/agent-gui/src-tauri/Cargo.toml --tests` (run from the repo root) **Gateway · `crates/agent-gateway` (if changed)** 1. Go unit tests pass: `go test ./...` 2. WebUI build / lint / tests pass: `pnpm build:webui && pnpm lint:webui && pnpm test:webui` 3. Regenerate and commit artifacts after proto changes: `make proto` **Shared UI boundaries** - Shared source must not depend directly on either host: `pnpm check:ui-boundaries` - Keep the diff clean (no trailing whitespace): `git diff --check` --- ## 👥 Contributors Thanks to everyone who has contributed to LiveAgent! --- ## Star History --- ## License MIT © StackCairn