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.
MCP Tools
Stella connects agents to remote MCP (Model Context Protocol) servers over streamable HTTP — with OAuth 2.1, bearer, or no auth — and installs new servers from the official MCP Registry marketplace in the Web UI. Every tool a server exposes is per-agent and per-user switchable, with the same four-scope permissions as everything else.
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
|
|
|
stellad/store
Package store is stellad's assembly layer: DBStore implements config.Store by composing the domain packages over one pgx pool.
|
Package store is stellad's assembly layer: DBStore implements config.Store by composing the domain packages over one pgx pool. |
|
internal
|
|
|
agent
Package agent runs Stella's agents: the pool of live agent services, the session registry, the runner factory, and the per-agent Settings policy that decides which management tools a turn may reach.
|
Package agent runs Stella's agents: the pool of live agent services, the session registry, the runner factory, and the per-agent Settings policy that decides which management tools a turn may reach. |
|
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/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. |
|
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
Package auth owns human identity: registration, login, session cookies, and the account records behind them.
|
Package auth owns human identity: registration, login, session cookies, and the account records behind them. |
|
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. |
|
authz
Package authz is the shared authorization vocabulary: Authority (who is acting), Action, and the resource identifiers domain services decide against.
|
Package authz is the shared authorization vocabulary: Authority (who is acting), Action, and the resource identifiers domain services decide against. |
|
channel
Package channel is the ingress side of every chat platform: the Channel interface plugins implement, identity resolution from a platform account to a Stella user, slash commands, and group dispatch.
|
Package channel is the ingress side of every chat platform: the Channel interface plugins implement, identity resolution from a platform account to a Stella user, slash commands, and group dispatch. |
|
connections
Package connections owns user-held OAuth connections: the bundles a user may connect, the flows that complete them, and the tokens the agent tools then spend.
|
Package connections owns user-held OAuth connections: the bundles a user may connect, the flows that complete them, and the tokens the agent tools then spend. |
|
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. |
|
core
Package core groups the leaf kernels every other internal package needs and that need almost nothing back: tool metadata, agent context keys, sentinel errors, agent access checks, provider credentials.
|
Package core groups the leaf kernels every other internal package needs and that need almost nothing back: tool metadata, agent context keys, sentinel errors, agent access checks, provider credentials. |
|
core/access
Package access is the policy-enforcement point for Agent resources.
|
Package access is the policy-enforcement point for Agent resources. |
|
core/providercred
Package providercred owns per-Agent LLM Provider API-key overrides.
|
Package providercred owns per-Agent LLM Provider API-key overrides. |
|
core/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. |
|
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
Package db owns PostgreSQL: pool construction, goose migrations, the embedded cluster used when no external server is configured, and the asset metadata for the embedded runtime tarball (pgruntime_asset.go).
|
Package db owns PostgreSQL: pool construction, goose migrations, the embedded cluster used when no external server is configured, and the asset metadata for the embedded runtime tarball (pgruntime_asset.go). |
|
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. |
|
db/pgruntime
Package pgruntime locates, names, and unpacks the bundled PostgreSQL runtime asset (versioned tarball, per-source cache directory, checksum URLs).
|
Package pgruntime locates, names, and unpacks the bundled PostgreSQL runtime asset (versioned tarball, per-source cache directory, checksum URLs). |
|
email
Package email is the user-owned mail capability: account configuration held in the acting user's vault, plus the list/read/send use cases the HTTP layer and the agent tools share.
|
Package email is the user-owned mail capability: account configuration held in the acting user's vault, plus the list/read/send use cases the HTTP layer and the agent tools share. |
|
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
|
|
|
grouptranscript
Package grouptranscript renders public group events into the model-facing transcript.
|
Package grouptranscript renders public group events into the model-facing transcript. |
|
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. |
|
library
Package library is the document library: raw storage, format detection, text derivation, retrieval, and the management tools over them.
|
Package library is the document library: raw storage, format detection, text derivation, retrieval, and the management tools over them. |
|
library/recally
Package recally provides file operations for article storage.
|
Package recally provides file operations for article storage. |
|
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. |
|
model
Package model groups everything about which LLM runs, what it costs, and what it embeds.
|
Package model groups everything about which LLM runs, what it costs, and what it embeds. |
|
model/catalog
Package catalog provides the embedded and optionally synchronized models.dev provider/model directory.
|
Package catalog provides the embedded and optionally synchronized models.dev provider/model directory. |
|
model/embedding
Package embedding turns text into vectors for semantic search.
|
Package embedding turns text into vectors for semantic search. |
|
model/usage
Package usage persists provider-reported LLM usage outside the turn path.
|
Package usage persists provider-reported LLM usage outside the turn path. |
|
notify
Package notify routes a notification to the channels that should receive it.
|
Package notify routes a notification to the channels that should receive it. |
|
oidc
Package oauth is Stella's OAuth2 authorization server (issue #613).
|
Package oauth is Stella's OAuth2 authorization server (issue #613). |
|
platform
Package platform groups the infrastructure packages that do not know agents exist: process/CLI plumbing, configuration, the STELLA_HOME layout, blob storage, observability, the bundled xberg CLI, build version, diagnostics.
|
Package platform groups the infrastructure packages that do not know agents exist: process/CLI plumbing, configuration, the STELLA_HOME layout, blob storage, observability, the bundled xberg CLI, build version, diagnostics. |
|
platform/blob
Package blob stores opaque bytes behind one interface, backed by S3-compatible object storage.
|
Package blob stores opaque bytes behind one interface, backed by S3-compatible object storage. |
|
platform/blob/blobtest
Package blobtest provides a filesystem-backed blob.Store for tests.
|
Package blobtest provides a filesystem-backed blob.Store for tests. |
|
platform/cli
Package cli is shared command plumbing for the stellad binary: dotenv loading and log-level parsing.
|
Package cli is shared command plumbing for the stellad binary: dotenv loading and log-level parsing. |
|
platform/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). |
|
platform/diagnostic
Package diagnostic renders potentially sensitive values for operator output.
|
Package diagnostic renders potentially sensitive values for operator output. |
|
platform/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. |
|
platform/observability
Package observability owns the process-global OpenTelemetry providers (tracer and logger).
|
Package observability owns the process-global OpenTelemetry providers (tracer and logger). |
|
platform/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. |
|
platform/version
Package version exposes the stella binary version.
|
Package version exposes the stella binary version. |
|
platform/xberg
Package xberg owns how Stella invokes the bundled Xberg CLI.
|
Package xberg owns how Stella invokes the bundled Xberg CLI. |
|
plugin
Package plugin groups the plugin machinery.
|
Package plugin groups the plugin machinery. |
|
plugin/host
Package host is the process-wide plugin platform.
|
Package host is the process-wide plugin platform. |
|
plugin/host/catalogimports
Package catalogimports registers every plugin included in Stella's default catalog.
|
Package catalogimports registers every plugin included in Stella's default catalog. |
|
plugin/manifest
Package manifest owns manifest-declared plugins: loading the builtin manifest, applying operator overrides, validating a plugin's shape, and reconciling its mise-installed runtime against what the manifest asks for.
|
Package manifest owns manifest-declared plugins: loading the builtin manifest, applying operator overrides, validating a plugin's shape, and reconciling its mise-installed runtime against what the manifest asks for. |
|
provisioning
Package provisioning owns the provisioned-user lifecycle.
|
Package provisioning owns the provisioned-user lifecycle. |
|
reflect
Package reflect is Stella's self-improvement loop: it reviews finished conversations on a scheduler builtin, gates candidates, reconciles the skills it owns, and curates skill usage.
|
Package reflect is Stella's self-improvement loop: it reviews finished conversations on a scheduler builtin, gates candidates, reconciles the skills it owns, and curates skill usage. |
|
scheduler
Package scheduler is the durable job service backed by River: cron and one-shot jobs created from the Web UI or from agent tools, executed under the owner's reconstructed Authority.
|
Package scheduler is the durable job service backed by River: cron and one-shot jobs created from the Web UI or from agent tools, executed under the owner's reconstructed Authority. |
|
searchrank
Package searchrank ranks documents by weighted text fields, so a domain can make (say) a skill name count for more than its body without each caller reimplementing scoring.
|
Package searchrank ranks documents by weighted text fields, so a domain can make (say) a skill name count for more than its body without each caller reimplementing scoring. |
|
server
Package server is the HTTP surface: the REST API generated from api/spec, SSE streaming, and the embedded React SPA.
|
Package server is the HTTP surface: the REST API generated from api/spec, SSE streaming, and the embedded React SPA. |
|
sessionmedia
Package sessionmedia persists immutable, owner-scoped bytes for session history.
|
Package sessionmedia persists immutable, owner-scoped bytes for session history. |
|
share
Package share turns an article or artifact into a public link with its own lifecycle: create, list, revoke.
|
Package share turns an article or artifact into a public link with its own lifecycle: create, list, revoke. |
|
skill
Package skill is the managed Skill authority: the durable store of installed skills at exact revisions, project and system skills merged read-only from the filesystem, search and loading for a turn, and the management tools.
|
Package skill is the managed Skill authority: the durable store of installed skills at exact revisions, project and system skills merged read-only from the filesystem, search and loading for a turn, and the management tools. |
|
skill/access
Package access owns the direct authorization rules for DB-backed Skill resources.
|
Package access owns the direct authorization rules for DB-backed Skill resources. |
|
skill/policy
Package policy owns the versioned Agent Skill activation setting.
|
Package policy owns the versioned Agent Skill activation setting. |
|
tools
Package tools holds the code generators run by mise tasks, not anything the server links.
|
Package tools holds the code generators run by mise tasks, not anything the server links. |
|
tools/generatebuiltinmanifest
command
|
|
|
tools/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>/. |
|
tools/syncmodelcatalog
command
Command syncmodelcatalog refreshes the compact models.dev snapshot embedded in stellad.
|
Command syncmodelcatalog refreshes the compact models.dev snapshot embedded in stellad. |
|
tools/toolgen
command
|
|
|
vault
Package vault stores per-user secrets encrypted at rest and hands them to the agent runtime as session environment variables.
|
Package vault stores per-user secrets encrypted at rest and hands them to the agent runtime as session environment variables. |
|
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. |
|
workflow
Package workflow stores and runs saved multi-step workflows: the durable definition, the run use case, and the agent tools over them.
|
Package workflow stores and runs saved multi-step workflows: the durable definition, the run use case, and the agent tools over them. |
|
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
|
|
|
fakeanthropic/cmd
command
|
|
|
testbed/cmd
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.