README
¶
English | 中文
Stella — Shared AI coworkers for every team
⚠️ Under Heavy Development — Stella is not stable. APIs, config formats, and behavior may change without notice. Not recommended for production use.
Stella turns the expertise your team repeats — finance, HR, engineering, research — into shared AI coworkers. Set an agent up once; everyone else just asks it in the chat tools they already use.
A domain owner gives an agent its instructions, skills, tools, knowledge, and memory rules. After that, nobody has to learn the finance system, the recruiting tool, or the internal toolchain to move work forward — they tell the agent the goal, and it does the work within the boundaries you set. Each person gets their own memory with the agent, so Stella understands different teammates without flattening everyone into one profile.
Under the hood it's a single-tenant, multi-user, multi-agent system: one deployment is one trust boundary, many people can rely on it at once, and each agent has its own role, model, skills, tools, schedules, workspace, and safety boundaries. Deploy it where you want, use your own model API keys, and reach it from Telegram, QQ, Feishu, WeChat, the Web UI, or the terminal.
Small teams and individual developers can run the same setup — one agent doing the back-office work no one has time for — but Stella is built first for teams who keep paying their experts to answer the same questions.
Why use Stella
- Anyone just asks. A teammate doesn't learn the finance or HR system to get help — they ask the agent in chat, and it does the work.
- One expert, shared by everyone. A domain owner builds an agent once; the whole team reuses it instead of interrupting the specialist.
- Remembers each teammate. Memory is scoped per user per agent, so nobody re-explains their context.
- Acts within boundaries you set. Agents work in dedicated workspaces with sandbox policies and controlled tool access, and stop for human review where you require it.
- Lives in the chat you already use. Telegram, QQ, Feishu, WeChat, the Web UI, and the terminal are all front doors to the same agents.
- 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/stellad@latest or download binaries from Releases.
See the full quickstart guide for detailed steps. To run Stella on Kubernetes, use the production Helm chart.
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 | |
| Webhook | Inbound HTTP POST with a PAT | No (sync or 202) |
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, Webhook setup | Channels |
| Admin | Kubernetes / Helm deployment | Kubernetes |
| 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
stellad upgrade 0.50.0 # Self-update to a specific release
stellad version # Print version
stellad vault keygen # Generate a vault bootstrap key
stellad mise reconcile-builtins # Reconcile builtin sandbox tools
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 |
|---|---|
|
cmd
|
|
|
stellad
command
|
|
|
internal
|
|
|
agent/access
Package access is the policy-enforcement point for Agent resources.
|
Package access is the policy-enforcement point for Agent resources. |
|
agent/runtime
Package runtime executes agent conversations in already-resolved sessions.
|
Package runtime executes agent conversations in already-resolved sessions. |
|
agent/sandbox
Package sandbox resolves an agent's sandbox config into a live session and provides that session's agent-facing tool projections (bash, read, write, edit).
|
Package sandbox resolves an agent's sandbox config into a live session and provides that session's agent-facing tool projections (bash, read, write, edit). |
|
agent/session
Package session owns agent-session lifecycle.
|
Package session owns agent-session lifecycle. |
|
agent/session/access
Package access is the authoritative Session and Workspace application service.
|
Package access is the authoritative Session and Workspace application service. |
|
asset
Package asset is the authoritative persistence boundary for uploaded user assets.
|
Package asset is the authoritative persistence boundary for uploaded user assets. |
|
auth/account
Package account is the application boundary for user-account management: the admin and self use cases over users, their login/channel identities, sessions, password credential, and agent assignments.
|
Package account is the application boundary for user-account management: the admin and self use cases over users, their login/channel identities, sessions, password credential, and agent assignments. |
|
cmd/toolgen
command
|
|
|
config
Package config currently holds two distinct concepts that share a package only for historical reasons (it is a leaf package everything can import without cycles).
|
Package config currently holds two distinct concepts that share a package only for historical reasons (it is a leaf package everything can import without cycles). |
|
controlplane
Package controlplane owns Stella's deployment control-plane resources: LLM providers, deployment settings (embedding, CLI-tool registry, OAuth provider config), plugins (registered + manifest), and channels.
|
Package controlplane owns Stella's deployment control-plane resources: LLM providers, deployment settings (embedding, CLI-tool registry, OAuth provider config), plugins (registered + manifest), and channels. |
|
credential
Package credential is the single front door for turning any bearer credential presented to the HTTP API into an authenticated Principal, and for enforcing what that principal may do.
|
Package credential is the single front door for turning any bearer credential presented to the HTTP API into an authenticated Principal, and for enforcing what that principal may do. |
|
db/dbtest
Package dbtest gives tests an isolated, fully-migrated PostgreSQL database with no external server to run.
|
Package dbtest gives tests an isolated, fully-migrated PostgreSQL database with no external server to run. |
|
embedding
Package embedding turns text into vectors for semantic search.
|
Package embedding turns text into vectors for semantic search. |
|
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). |
|
goal
Package goal is the recursive execution core: one entity (the Goal) whose completion is DERIVED from an append-only acceptance ledger, never asserted.
|
Package goal is the recursive execution core: one entity (the Goal) whose completion is DERIVED from an append-only acceptance ledger, never asserted. |
|
goal/cmd/gengoalcontrolschema
command
|
|
|
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. |
|
inbox
Package inbox is the cross-Goal/Scheduler inbox read model: it owns the two candidate queries (blocked/failed goals and failed scheduler runs), merges them, applies a stable recency sort, and paginates, returning transport-neutral domain items.
|
Package inbox is the cross-Goal/Scheduler inbox read model: it owns the two candidate queries (blocked/failed goals and failed scheduler runs), merges them, applies a stable recency sort, and paginates, returning transport-neutral domain items. |
|
mcp
Package mcp is an MCP (Model Context Protocol) client for Stella.
|
Package mcp is an MCP (Model Context Protocol) client for Stella. |
|
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 durable memory surfaces.
|
Package memorywrite provides shared transactional write helpers for durable memory surfaces. |
|
memory/profile
Package profile is the application boundary for per-(user, agent) memory: the profile blob, agent soul, hard constraints, reset, and the change history.
|
Package profile is the application boundary for per-(user, agent) memory: the profile blob, agent soul, hard constraints, reset, and the change history. |
|
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. |
|
oidc
Package oauth is Stella's OAuth2 authorization server (issue #613).
|
Package oauth is Stella's OAuth2 authorization server (issue #613). |
|
recally
Package recally provides file operations for article storage.
|
Package recally provides file operations for article storage. |
|
skillaccess
Package skillaccess owns the direct authorization rules for DB-backed Skill resources.
|
Package skillaccess owns the direct authorization rules for DB-backed Skill resources. |
|
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. |
|
db/pgnull
Package pgnull builds nullable pgx column values from plain Go values, collapsing the empty value to SQL NULL.
|
Package pgnull builds nullable pgx column values from plain Go values, collapsing the empty value to SQL NULL. |
|
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. |
|
renderrefs
Package renderrefs defines the sideband protocol for lifting references from tool output so the chat UI can render a rich card instead of a raw UUID.
|
Package renderrefs defines the sideband protocol for lifting references from tool output so the chat UI can render a rich card instead of a raw UUID. |
|
plugins
|
|
|
channels/webhook
Package webhook registers the inbound-only webhook channel.
|
Package webhook registers the inbound-only webhook channel. |
|
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. |
Click to show internal directories.
Click to hide internal directories.