README
¶
English | 中文
Stella — AI partners for every person
⚠️ Under Heavy Development — Stella is not stable. APIs, config formats, and behavior may change without notice. Not recommended for production use.
Stella gives every person an AI partner that remembers them, works through trusted tools, and shows up where they already chat.
Use Stella as a teammate at work, a manager for home routines, or a private assistant for personal projects. Each user-agent relationship has its own memory, workspace, tools, schedules, and sandbox boundaries, so Stella can understand different people without flattening everyone into one profile.
Under the hood, Stella is a multi-tenant, multi-user, multi-agent system. Each agent can have its own role, model, skills, tools, schedules, workspace, and sandbox policy. Deploy Stella where you want, use your own model API keys, and talk to her from Telegram, QQ, Feishu, WeChat, the Web UI, or the terminal.
Why use Stella
- Remembers each person. Memory is scoped per user per agent, so Stella understands different people differently.
- Works through agents. Create agents for coding, writing, operations, family routines, research, and support.
- Acts safely. Agents work in dedicated workspaces with sandbox policies and controlled tool access.
- Meets you in chat. Telegram, QQ, Feishu, WeChat, the Web UI, and the terminal all become front doors to the same AI partner system.
- Keeps routines moving. Schedule reminders, recurring jobs, reading digests, and background tasks that persist across restarts and notify the right people.
Quick start
# 1. Install
brew install CherryHQ/tap/stella
# 2. Start the server
stellad server
# 3. Open the Web UI at http://localhost:25678
# Add your provider and API key under Providers
# 4. Open Chat and start talking
You can also install with go install github.com/CherryHQ/stella/cmd/stella@latest && go install github.com/CherryHQ/stella/cmd/stellad@latest or download binaries from Releases.
See the full quickstart guide for detailed steps.
Connect your channels
All channels share the same memory. Chat from one, switch to another, and Stella picks up where you left off.
| Channel | How to connect | Streaming support |
|---|---|---|
| Terminal | Built-in TUI | Token-by-token |
| Telegram | Long polling, no public IP | Yes |
| WebSocket | Yes | |
| Feishu | WebSocket, no public IP | Edit-in-place |
| Long polling (iLink Bot) | No |
You can bind a channel to a specific agent, or let users switch agents with /agent.
Skills
Skills are reusable playbooks that teach Stella how to perform specific tasks. Stella manages skills through a built-in tool — ask her to search, install, or load skills directly in conversation.
Documentation
| Section | What's inside | Link |
|---|---|---|
| Getting Started | Install, deploy, configure | Quick Start |
| Guides | Memory, scheduling, skills, notifications | Guides |
| Channels | Telegram, QQ, Feishu, WeChat setup | Channels |
| Development | Architecture, plugins, contributing | Development |
CLI reference
stellad server # Start server; Web UI at http://localhost:25678
stellad server --port 8080 # Custom port
stellad upgrade # Self-update to latest release
stella scheduler list # List scheduled jobs
stella vault list # List stored secrets
stella version # Print version
Development
Development requires mise. On a fresh clone:
mise run setup # Set up dev environment and pre-commit hooks
mise run build # Build binary
mise run test # Run tests
mise run format # Lint and format
License
GNU Affero General Public License v3.0 or later. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
api
|
|
|
cmd
|
|
|
stella
command
|
|
|
stellad
command
|
|
|
internal
|
|
|
agent/runtime
Package runtime executes agent conversations in already-resolved sessions.
|
Package runtime executes agent conversations in already-resolved sessions. |
|
agent/session
Package session owns agent-session lifecycle.
|
Package session owns agent-session lifecycle. |
|
db/ftsquery
Package ftsquery builds safe FTS5 MATCH expressions from free text.
|
Package ftsquery builds safe FTS5 MATCH expressions from free text. |
|
eventlog
Package eventlog owns the authoritative, deduplicated group-message log (ctx_group_message) and its per-group ordering registry (ctx_group_state).
|
Package eventlog owns the authoritative, deduplicated group-message log (ctx_group_message) and its per-group ordering registry (ctx_group_state). |
|
groupingest
Package groupingest consumes the group event log and extracts memories into group-shared and per-user drawers.
|
Package groupingest consumes the group event log and extracts memories into group-shared and per-user drawers. |
|
memory
Package memory defines the pluggable memory provider contract.
|
Package memory defines the pluggable memory provider contract. |
|
memory/memorytest
Package memorytest provides test doubles and conformance testing for memory.Provider implementations.
|
Package memorytest provides test doubles and conformance testing for memory.Provider implementations. |
|
memory/memorywrite
Package memorywrite provides shared transactional write helpers for profile and soul memory updates.
|
Package memorywrite provides shared transactional write helpers for profile and soul memory updates. |
|
observability
Package observability owns the process-global OpenTelemetry providers (tracer and logger).
|
Package observability owns the process-global OpenTelemetry providers (tracer and logger). |
|
observability/tracehook
Package tracehook is the core agent trace hook: it logs LLM, tool, and memory activity via slog and, when OTel tracing is enabled, records the session/turn/LLM/tool/memory span hierarchy.
|
Package tracehook is the core agent trace hook: it logs LLM, tool, and memory activity via slog and, when OTel tracing is enabled, records the session/turn/LLM/tool/memory span hierarchy. |
|
recally
Package recally provides file operations for article storage.
|
Package recally provides file operations for article storage. |
|
version
Package version exposes the stella binary version.
|
Package version exposes the stella binary version. |
|
pkg
|
|
|
channel
Package channel defines the public contract for channel plugins.
|
Package channel defines the public contract for channel plugins. |
|
httpclient
Package httpclient provides a shared resty HTTP client factory with optional OpenTelemetry tracing.
|
Package httpclient provides a shared resty HTTP client factory with optional OpenTelemetry tracing. |
|
plugins
Package plugins defines the shared plugin-facing contracts for Stella's unified plugin host.
|
Package plugins defines the shared plugin-facing contracts for Stella's unified plugin host. |
|
plugins
|
|
|
sandbox/docker/dockerclient
Package dockerclient wraps the moby Go SDK (github.com/moby/moby/client) to manage sandbox containers for the docker sandbox backend.
|
Package dockerclient wraps the moby Go SDK (github.com/moby/moby/client) to manage sandbox containers for the docker sandbox backend. |
|
sandbox/local
Hardening layers applied: process-group isolation on Unix, rlimits on Linux, bwrap filesystem/network isolation on Linux, macOS Seatbelt (sandbox-exec) filesystem and network isolation on macOS.
|
Hardening layers applied: process-group isolation on Unix, rlimits on Linux, bwrap filesystem/network isolation on Linux, macOS Seatbelt (sandbox-exec) filesystem and network isolation on macOS. |
|
sandbox/none
Package none provides a no-op sandbox backend that runs commands directly on the host with the same permissions as the current user and no isolation.
|
Package none provides a no-op sandbox backend that runs commands directly on the host with the same permissions as the current user and no isolation. |
|
Package resources bundles embedded resources (skills, souls, delegates, templates, and builtin plugin manifest) that Stella ships with its binary.
|
Package resources bundles embedded resources (skills, souls, delegates, templates, and builtin plugin manifest) that Stella ships with its binary. |