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, Discord, QQ, Feishu, DingTalk, 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, Discord, QQ, Feishu, DingTalk, 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 download binaries from Releases, or build from source with git clone and mise run build. go install is not supported: the binary embeds generated code, the Web UI, and the bundled runtimes, none of which are in version control.
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 |
| Discord | Gateway WebSocket | Final response |
| WebSocket | Yes | |
| Feishu | WebSocket, no public IP | Edit-in-place |
| DingTalk | Stream mode, no public IP | Final response |
| Long polling (iLink Bot) | No |
You can bind each channel to a specific agent in the Web UI.
Skills
Skills are reusable playbooks that teach Stella how to perform specific tasks. In conversation, Stella can search the Skills already available to the active Agent and load an exact revision. Install, upload, edit, and remove Skills from the Web UI, where every write has an explicit ownership scope.
Release-provided skills are read-only; administrators manage shared skills separately. See the Skills guide for scopes, per-Agent activation, and precedence.
Documentation
| Section | What's inside | Link |
|---|---|---|
| Getting Started | Install, deploy, configure | Quick Start |
| Guides | Memory, scheduling, skills, notifications | Guides |
| Channels | Telegram, Discord, QQ, Feishu, DingTalk, WeChat | Channels |
| Webhooks | Personal HTTP invocation capabilities | Webhooks |
| 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
|
|
|
stella-eval-agent
command
stella-eval-agent drives one Harbor evaluation trial through Stella's public HTTP API.
|
stella-eval-agent drives one Harbor evaluation trial through Stella's public HTTP API. |
|
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/providercred
Package providercred owns per-Agent LLM Provider API-key overrides.
|
Package providercred owns per-Agent LLM Provider API-key overrides. |
|
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. |
|
agent/session/inbox
Package inbox persists Agent-originated Session inputs without owning their execution.
|
Package inbox persists Agent-originated Session inputs without owning their execution. |
|
agent/session/turnqueue
Package turnqueue serializes synchronous agent-originated turns per Session.
|
Package turnqueue serializes synchronous agent-originated turns per Session. |
|
agent/settingspolicy
Package settingspolicy owns the narrow discovery and turn-capability boundary for conversational Settings tools.
|
Package settingspolicy owns the narrow discovery and turn-capability boundary for conversational Settings tools. |
|
agent/toolmeta
Package toolmeta describes generated model-facing tools: the name, the family it belongs to, and the exact input schema bound to one action.
|
Package toolmeta describes generated model-facing tools: the name, the family it belongs to, and the exact input schema bound to one action. |
|
agentskillpolicy
Package agentskillpolicy owns the versioned Agent Skill activation setting.
|
Package agentskillpolicy owns the versioned Agent Skill activation setting. |
|
asset
Package asset stores immutable session media outside mutable workspace and user-data trees.
|
Package asset stores immutable session media outside mutable workspace and user-data trees. |
|
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/generatebuiltinmanifest
command
|
|
|
cmd/syncembeddedbinaries
command
Command syncembeddedbinaries downloads the third-party runtimes that get compiled into stellad and writes them to resources/binaries/binaries/<platform>/.
|
Command syncembeddedbinaries downloads the third-party runtimes that get compiled into stellad and writes them to resources/binaries/binaries/<platform>/. |
|
cmd/syncmodelcatalog
command
Command syncmodelcatalog refreshes the compact models.dev snapshot embedded in stellad.
|
Command syncmodelcatalog refreshes the compact models.dev snapshot embedded in stellad. |
|
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. |
|
diagnostic
Package diagnostic renders potentially sensitive values for operator output.
|
Package diagnostic renders potentially sensitive values for operator output. |
|
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
|
|
|
home
Package home owns the single-replica POSIX workspace layout beneath STELLA_HOME.
|
Package home owns the single-replica POSIX workspace layout beneath STELLA_HOME. |
|
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. |
|
llmusage
Package llmusage persists provider-reported LLM usage outside the turn path.
|
Package llmusage persists provider-reported LLM usage outside the turn path. |
|
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. |
|
modelcatalog
Package modelcatalog provides the embedded and optionally synchronized models.dev provider/model directory.
|
Package modelcatalog provides the embedded and optionally synchronized models.dev provider/model directory. |
|
modelresolve
Package modelresolve owns the one effective-model merge used by the control plane and runtime snapshot.
|
Package modelresolve owns the one effective-model merge used by the control plane and runtime snapshot. |
|
observability
Package observability owns the process-global OpenTelemetry providers (tracer and logger).
|
Package observability owns the process-global OpenTelemetry providers (tracer and logger). |
|
observability/metrichook
Package metrichook records bounded agent-loop metrics from the core hook payloads.
|
Package metrichook records bounded agent-loop metrics from the core hook payloads. |
|
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). |
|
pluginhost/catalogimports
Package catalogimports registers every plugin included in Stella's default catalog.
|
Package catalogimports registers every plugin included in Stella's default catalog. |
|
provisioning
Package provisioning owns the provisioned-user lifecycle.
|
Package provisioning owns the provisioned-user lifecycle. |
|
recally
Package recally provides file operations for article storage.
|
Package recally provides file operations for article storage. |
|
sessionmedia
Package sessionmedia persists immutable, owner-scoped bytes for session history.
|
Package sessionmedia persists immutable, owner-scoped bytes for session history. |
|
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. |
|
vision
Package vision turns verified image bytes into bounded text.
|
Package vision turns verified image bytes into bounded text. |
|
webhook
Package webhook owns personal webhook resources, their opaque credentials, and the admission boundary from inbound HTTP to a fixed Agent invocation.
|
Package webhook owns personal webhook resources, their opaque credentials, and the admission boundary from inbound HTTP to a fixed Agent invocation. |
|
xberg
Package xberg owns how Stella invokes the bundled Xberg CLI.
|
Package xberg owns how Stella invokes the bundled Xberg CLI. |
|
pkg
|
|
|
channel
Package channel defines the public contract for channel plugins.
|
Package channel defines the public contract for channel plugins. |
|
codemode
Package codemode hosts the isolated QuickJS feasibility runtime for Code Mode.
|
Package codemode hosts the isolated QuickJS feasibility runtime for Code Mode. |
|
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. |
|
db/txlock
Package txlock provides transaction-scoped PostgreSQL advisory locks shared by persistence packages without creating internal package import cycles.
|
Package txlock provides transaction-scoped PostgreSQL advisory locks shared by persistence packages without creating internal package import cycles. |
|
goldmark/mdutil
Package mdutil holds small markdown source scanners shared by the channel renderers.
|
Package mdutil holds small markdown source scanners shared by the channel renderers. |
|
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. |
|
otelenv
Package otelenv answers one question from the standard OpenTelemetry environment variables: is this signal being exported?
|
Package otelenv answers one question from the standard OpenTelemetry environment variables: is this signal being exported? |
|
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
|
|
|
sandbox/bridge
Package bridge is an evaluation-only sandbox backend.
|
Package bridge is an evaluation-only sandbox backend. |
|
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. |
|
test
|
|
|
perf/fakeprovider
command
Command fakeprovider is a deterministic stand-in for the Anthropic Messages API, used by the chat perf harness (test/perf/run.sh).
|
Command fakeprovider is a deterministic stand-in for the Anthropic Messages API, used by the chat perf harness (test/perf/run.sh). |
|
testbed
command
Command testbed runs a disposable local Stella instance for API and browser tests.
|
Command testbed runs a disposable local Stella instance for API and browser tests. |
|
toolgenfixture
Package toolgenfixture pins toolgen's declaration-only path against a real package: agent-tools/session.yaml is generated into tool_gen.go here, and this file supplies both the hand-written type the generated names must not collide with and a Handler implementation the generated Dispatch must accept.
|
Package toolgenfixture pins toolgen's declaration-only path against a real package: agent-tools/session.yaml is generated into tool_gen.go here, and this file supplies both the hand-written type the generated names must not collide with and a Handler implementation the generated Dispatch must accept. |
Click to show internal directories.
Click to hide internal directories.