# Sero > Grow your own Agent with workspaces, memory, skills, and plugins. ## How Sero Works - [Grow your own Agent](/guide/overview.md): Sero gives an AI coding agent its own desktop workspace. It can work with your project files, run commands, open previews, use a browser, and call tools while you inspect and steer the work as it runs. Add your instructions, memory, skills, and plugins. The agent keeps useful context and gains new capabilities as you add them. That is what we mean by "grow your own Agent." Sero is a packaged desktop release for macOS, Linux and Windows. It runs on your computer, not in a hosted cloud IDE. Sero is built on the open-source Pi coding agent. ## Workspace - [Workspace and Chat](/guide/workspace-and-chat.md): Sero opens into a persistent desktop workspace: a left navigation sidebar, a central app surface, and a global chat panel that can stay available while you move between apps. This guide explains the basic mental model. For the detailed chat composer, attachments, context editor, slash commands, steering, queued follow-ups, and voice input, see Agent Sessions and Context. ## Agents - [Agent Sessions and Context](/guide/agent-sessions-and-context.md): The chat panel is where you ask Sero to plan, inspect files, edit code, use tools, and explain what it is doing. This guide covers the day-to-day composer controls that help you give the agent useful context without assuming that every saved detail is included on every turn. ## Plugins - [Plugin Catalog](/plugins/catalog.md): Use this catalog to identify who supplies a plugin and whether a current path is verified. A documentation page does not by itself mean that Sero supports the plugin. ## Others - [Connect to an Agent Node](/guide/agent-node.md): Agent Node runs a persistent Sero agent on a Linux computer. Sero Desktop controls the node. The agent can continue work when Desktop disconnects. Agent Node supports Linux x64 and Linux arm64. NVIDIA DGX Spark is a supported arm64 target. AWS Bedrock is not supported on Agent Node. Use another provider or a local OpenAI-compatible endpoint. - [App Store, Favorites, and Installed Plugins](/guide/app-store-favorites.md): Use App Store to find plugin apps, install external plugins, and choose which plugin apps appear in the sidebar. - [Architect](/guide/architect.md): Sero Architect manages work across a product instead of one task. Give it a request and a start cap. It plans the work, builds it through Workflows and Rooms or does small pieces itself, and checks the result. The cap stops new work when reported spend reaches it; active requests can still add cost. Architect checks the result before it moves on to release and maintenance. It asks for your input when it needs a decision. Use Architect when you want Sero to take a product from idea through maintenance. Use Orchestrator when you want to run one Workflow, Room or Goal yourself. - [Browser and Capture](/guide/browser-and-capture.md): Sero has two related visual surfaces: the visible Explorer browser, which opens workspace-scoped browser tabsthe UI-backed app/capture bridge, which can switch apps, inspect UI, capture screenshots, preview dev servers, and record short MP4s They are useful for development previews, support reports, and agent/operator workflows, but they are not a replacement for a full browser automation framework. - [Checkpoints and Undo](/guide/checkpoints-and-undo.md): Sero has two related recovery actions. A manual checkpoint creates a Git commit from all current workspace changes. Undo this turn restores an internal snapshot and rewinds the selected chat session. Both actions change real workspace files. - [Choose a Workspace Runtime](/guide/choose-workspace-runtime.md): A workspace runtime is where Sero runs commands for one project. Choose the runtime per workspace, so different projects can use different execution environments. Host runs commands directly in your project folder. It uses compatible tools on your computer and 127.0.0.1 preview URLs.Apple Container runs commands inside a Sero-managed container on supported Apple Silicon Macs.Docker / Podman runs commands inside a Sero-managed Linux container using Docker-compatible tooling. If you are unsure, keep Host. Host is the default on supported platforms. Choose a container runtime only when you want container behavior for that workspace. For the exact platform support matrix, see Support Scope. For dev-server preview steps, see Preview Dev Servers. - [Code Mode](/guide/codemode.md): Code Mode lets the agent write a short JavaScript program that calls its available tools and processes their results. You give Sero a task in chat. The agent uses codemode to read data, combine tool calls, and return the answer. You review the answer and any changes it made. For example, an agent can read several JSON files, count records by status, and return a small table. The full contents of each file stay inside that run unless the program returns them. This can reduce the tool output sent back to the model and the number of model turns needed to complete the task. The saving depends on the task and what the program returns. - [Preview Dev Servers](/guide/containers-dev-servers.md): Use this guide to start a project dev server, register it with Sero, and open the preview URL. This page is task-focused. To choose Host, Apple Container, or Docker / Podman first, see Choose a Workspace Runtime. For the exact support matrix, see Support Scope. - [Dashboard and Widgets](/guide/dashboard-widgets.md): Dashboard is Sero's home surface for compact app and workspace summaries. Widgets are small panels contributed by the host or by installed apps/plugins; they are useful for status at a glance, not a replacement for opening the full app. - [Development Setup](/guide/development-setup.md) - [Explorer](/guide/explorer-workspace.md): Explorer is Sero's project workspace editor. It brings together files, editor previews, browser/preview tabs, source-control views, and workspace terminals around the active workspace and agent session. For runtime behavior, see Containers and Host Mode. For dev-server setup, see Containers and Dev Servers. - [Get Sero Running](/guide/getting-started.md): Install the packaged desktop app, complete setup, and open a workspace. If you want to change Sero itself, use Development Setup instead. - [Git](/guide/git-integration.md): Sero has a built-in Git app for working in a repository. It gives you and the agent the same view of branches, changes, commits, diffs and stashes, and it can carry out most everyday Git operations. The Git app changes the active repository. Review a diff before you stage, commit, discard, merge, or push changes. - [Goals](/guide/goals.md): A Goal keeps one chat session working toward a result. Give Sero an objective and, when useful, a short list of checks. The session continues after each reply until the agent reports completion, needs your help, reaches a limit, or you stop it. Use a Goal when the result is clear but the route is not. Use a Workflow when Sero can plan the steps first. Use a Room when the work needs several agents. - [Guides](/guide/index.md): Use guides when you want to complete a task. This section keeps the existing guide/ paths, but the reading order follows Diátaxis: first-run tutorials first, then task how-tos, then links to reference facts when you need exact details. If you need the exact platform or runtime support contract, use Support Scope instead of this index. - [Install Sero](/guide/installation-requirements.md) - [Local LLMs with LM Studio](/guide/local-llms-lm-studio.md): LM Studio can run a local model server that Sero treats like an OpenAI-compatible provider. Use this when you want to test local models, work with private local endpoints, or avoid sending a specific task to a hosted model provider. Local models still need enough memory and GPU/CPU capacity on your machine. They may be slower or less capable than hosted models, and they are not automatically available inside every workspace container unless the URL is reachable from the process that needs it. - [MCP](/guide/mcp.md): An MCP (Model Context Protocol) server gives the agent more tools and data, for example access to an issue tracker or a database. Use the MCP app to add, inspect, change, and remove the MCP servers of the active profile. A server can be a local command that Sero starts, or a remote service that Sero connects to. Each server row shows the server status, for example connected, and the protocol revision in use. - [Memory](/guide/memory.md): Sero Memory is a built-in plugin (@sero-ai/plugin-memory) that lets the chat agent keep important or surprising facts about you and your projects across sessions. A fact reaches the agent only when it applies, so memory changes behaviour without filling every turn with old context. See the Plugin Catalog for the built-in plugin inventory. Treat memory as helpful context, not as perfect recall or an audit log. - [Models and Providers](/guide/models-and-providers.md): Sero uses providers for model access and model tiers for everyday choices. A profile can use hosted API-key providers, OAuth-backed providers from the Pi SDK, plugin-defined providers, and local/custom providers from models.json. Sero does not bundle third-party credentials. You connect your own accounts, API keys, environment-backed credentials, or local endpoints. Sero reads authentication methods from the active Pi provider metadata. Saved credentials stay in the desktop main process. Environment credentials are shown as environment-backed and are not overwritten when you change a saved key. - [Orchestrator](/guide/orchestrator.md): Orchestrator lets Sero's AI agents work on a task without you directing every step. You describe the result you want, review how Sero plans to do the work, and decide when it can start. Open Orchestrator from the app bar, then choose Workflows or Rooms. A third mode, Goals, starts in the chat session itself with /goal, and Orchestrator manages the ones you leave running. - [Plugins and Apps](/guide/plugins-and-apps.md): Plugins extend Sero. They can add an app UI, agent tools and commands, background services, model or service providers, and dashboard widgets. Warning: An installed plugin can execute code on your device and access your workspace. Install plugins only from sources that you trust. - [Profiles and Onboarding](/guide/profiles-and-onboarding.md): Profiles keep separate Sero working environments, such as Work, Personal, or Research. Each profile has a SERO_HOME directory. Sero stores that profile's agent files under /agent/. Profiles are practical local separation, not cryptographic isolation. Someone who can read your profile folder can read sensitive profile files such as provider auth, environment variables, prompts, memory, and workspace metadata. - [Remote Control](/guide/remote-control.md): Remote Control lets you operate your local Sero desktop session from another trusted client. It is off by default and only starts when the desktop process is launched with: Remote Control is not screen sharing and is not production remote administration. The work still happens on your desktop machine, in your active local Sero profile. Remote clients are alternate control surfaces for the Sero desktop process that is already running locally. Remote Control has three related integration paths: Remote web access over Tailscale — a browser UI called Sero Remote can connect to your local Sero gateway from another trusted device on your Tailscale tailnet.Remote dev-server previews — dev servers started and registered inside Sero desktop can be opened through Sero Remote, so a Vite/Next/Express/etc. preview running on your desktop machine or workspace container is reachable from another trusted tailnet browser.Optional Discord bot — a configured Discord bot can forward allowed DMs or mentions into Sero as prompts. Tailscale is the private VPN/tailnet layer for remote web access. Discord is a separate optional bot integration; it does not depend on Tailscale and it does not provide the Sero Remote web UI. Read Security / Privacy before enabling Remote Control. - [Manage a Room](/guide/rooms-advanced.md): This guide explains how Sero keeps member changes separate, how to respond to access requests, how to change a team, and how to recover a stopped Room. Start with Create a Room if you have not run one yet. See the Rooms reference for all statuses, fields, and limits. - [Rooms](/guide/rooms.md): A Room gives one task to a temporary team of Sero agents. Each member has a role. Members can work at the same time, share findings, and change how they divide the task. Use a Room when a task needs several roles or points of view. Use a Workflow when Sero can follow a plan of steps instead. Orchestrator explains the difference. - [Running Evals](/guide/running-evals.md): Use Sero evals when you need a structured signal about prompt assembly or agent behavior. Snapshot evals are fast and local. Real LLM evals call providers and can cost money. - [Scheduler and Reminders](/guide/scheduler-reminders.md): Sero's Scheduler is a built-in plugin (@sero-ai/plugin-cron) for simple automations: recurring agent prompts, one-time reminders, and recurring reminders. It is useful for lightweight checks such as "summarize this demo inbox every weekday" or "remind me to review this synthetic plan tomorrow." Source checked: plugins/sero-cron-plugin/package.json and README. See the Plugin Catalog for the built-in plugin inventory. Scheduler is local automation. It does not guarantee delivery and does not replace a calendar, monitoring service, or notification service. - [Settings and Admin](/guide/settings-models-admin.md): Sero's Admin app is provided by the built-in @sero-ai/plugin-admin package. It collects profile-level configuration, local agent resources, session inspection, and other support-oriented surfaces. Use this page as the entry point for Admin-related documentation. - [Subagents](/guide/subagents.md): Subagents let the main Sero agent delegate bounded work to specialist child sessions. Use them when one task can be split into independent research, review, testing, or implementation tracks. - [Themes](/guide/themes.md): Sero stores the selected theme and light, dark, or system mode in the active profile's layout state. Custom theme presets are also profile-scoped. - [Web](/guide/web.md): Sero's Web plugin is a built-in plugin (@sero-ai/plugin-web) for bringing web context into an agent session. It can search the web, fetch readable content from sources you provide, retrieve previously stored search/fetch content, run code-oriented web lookups, and keep workspace-scoped bookmarks and activity for later review. See the Plugin Catalog for the built-in plugin inventory. Web access depends on configured providers, local runtime support from Support Scope, signed-in browser/profile state for some paths, and third-party services that can change outside Sero. - [Manage Workflows](/guide/workflows-advanced.md): This guide explains how to improve a Workflow from its run history, save what it proved as a skill, run it automatically, change one step, recover from an error, and reuse it in another workspace. Start with Create a Workflow if you have not made one yet. See the Workflows reference for all commands, limits, and storage paths. - [Workflows](/guide/workflows.md): A Workflow turns a requirement into a plan that Sero can run more than once. Describe the result in plain language. Sero chooses the steps, their order, and the routes through the work. The plan is not a fixed template. A research Workflow might collect sources in parallel and then write a report. A maintenance Workflow might stop when there is nothing to fix. A coding Workflow can inspect an issue, choose an approach, run checks, and open a pull request. Use a Room when several agents need to work as a team. See Orchestrator for a comparison. - [Design Library](/plugins/design-library.md): Design Library turns visual references into generated web designs. It keeps references, work in progress, and saved Gallery versions in the active Sero profile. - [Google Plugin](/plugins/google.md): Google adds Gmail and Google Calendar to Sero. It uses the gog command from gogcli. - [Graphify](/plugins/graphify.md): Graphify builds a local knowledge graph for selected workspaces. It maps code symbols and their connections, then merges workspace graphs so that you and the agent can search across projects. - [ImageGen Plugin](/plugins/imagegen.md): ImageGen creates images with the Google Gemini API. Open ImageGen to generate an image, browse the Gallery, or view a result at full size. - [Loom](/plugins/loom.md): Loom is maintained in the Loom repository. Loom is an infinite generative-art studio where you describe an idea and Sero creates a living shader artwork. It can inspect the rendered result, make a refinement when needed, and give the finished piece a small set of controls that suit that particular artwork. - [Notes Plugin](/plugins/notes.md): Notes keeps a notebook for the active Sero profile. Open Notes to write and search notes, or use the agent to manage them. The Pinboard dashboard widget shows pinned and recent notes. - [Plan Mode Plugin](/plugins/plan-mode.md): Plan Mode separates read-only investigation from implementation. Use it when you want to inspect a task and approve a saved plan before the agent changes files. - [Research Plugin](/plugins/research.md): Research splits a question into parallel agent workstreams and then synthesizes their results. Use public, low-risk material for your first run. - [Search](/plugins/search.md): The Search plugin gives your agent indexed file and content search. It is built in and enabled by default, so there is nothing to install. - [Signal Desk Plugin](/plugins/signal-desk.md): Signal Desk collects RSS and Atom feeds, groups related items into stories, and keeps briefings, insights, and follow-up actions. - [Spotify Plugin](/plugins/spotify.md): Status: Deprecated. The current plugin repository marks this plugin as deprecated. It is not recommended for new use. The Spotify plugin route stays available for users who find old setup links. The former plugin used Spotify OAuth with PKCE for account access and used Spotify's Web Playback SDK for playback. - [Starling Bank Plugin](/plugins/starling.md): The Starling Bank plugin is an external plugin. Install it from its owner with this source: The plugin shows balances, transactions, savings goals, and spending information. It only reads data from Starling. Its current Personal Access Token scopes are: account:readbalance:readtransaction:readsavings-goal:read Create the token at developer.starlingbank.com. The plugin needs an internet connection and sends authenticated GET requests to https://api.starlingbank.com/api/v2. The app also requests Google Fonts from fonts.googleapis.com when it loads its styles. - [Todo Plugin](/plugins/todo.md): Todo keeps a task list for the current workspace. Use the Todo app for direct changes, or ask the agent to update the list. - [User Feedback](/plugins/user-feedback.md): User Feedback lets an agent stop and ask for a decision. It provides a compact Chat question, a step-by-step questionnaire, and an open-ended interview. You do not install or configure this built-in plugin. Its tools are available to agent sessions, but the manifest sets bridgeTools to false. Other plugin apps cannot call them through the app tool bridge. - [Weight Tracker Plugin](/plugins/weight-tracker.md): The Weight Tracker is an external plugin for personal weight records. Install it from its owner with this source: The app records a weight, date, and optional note. It shows a trend chart, changes over time, and progress towards a goal. The weight tool supports log, list, remove, goal, status, and clear. The /weight command shows the same records in an agent session. - [Agent Definitions Reference](/reference/agent-definitions.md): Agent definitions are profile-scoped Markdown files that describe named subagents. The Markdown body becomes the subagent system prompt; JSON frontmatter supplies metadata such as name, description, model, thinking, and timeout. - [Agent Node Operations](/reference/agent-node-operations.md): This page is for the Linux operator. Agent Node supports Linux x64 and Linux arm64. NVIDIA DGX Spark is an arm64 target. Do not use AWS Bedrock with Agent Node. - [Agent Node troubleshooting](/reference/agent-node-troubleshooting.md): This page is for the Linux operator. Use it when Desktop cannot connect or when a command works over SSH but fails through Agent Node. - [Agent Plugins](/reference/agent-plugins.md): Install portable Agent Plugins with Agent Skills and MCP servers. - [App Runtime Reference](/reference/app-runtime.md): @sero-ai/app-runtime connects a plugin's React UI to the Sero host. Use it only in modules that Sero loads. It is not an API for standalone browser apps. - [Architect reference](/reference/architect.md): This page lists runtime facts for Sero Architect. See Architect for the user guide. - [Architecture](/reference/architecture.md) - [Container Isolation](/reference/container-isolation.md): Container runtimes run workspace commands inside Sero-managed containers. Apple Container and Docker / Podman provide container mounts, container networking behavior, runtime-image tooling, browser automation from the image, and per-workspace dev-server previews. They are not documented as a hardened multi-tenant security boundary. Host is the direct-host runtime where supported. It uses the real host workspace directory and normal host networking rather than container mounts or container network semantics. For the exact public support matrix, see Support Scope. For choosing a runtime, see Choose a Workspace Runtime. - [Containers and Host Mode](/reference/containers-host-mode.md): Sero can run each workspace through Host, Apple Container, or Docker / Podman. This page records runtime behavior and failure rules. For choosing a runtime, see Choose a Workspace Runtime. For the canonical platform support matrix, see Support Scope. Selected container runtimes fail closed when unavailable: Sero reports diagnostics for the selected runtime. It does not silently run that selected container workspace on Host. Fix the container runtime or explicitly choose another supported runtime. For dev-server steps, see Preview Dev Servers. For lifecycle, mounts, and networking details, see Container Isolation. - [Dashboard Components](/reference/dashboard-components.md): @sero-ai/ui provides shared dashboard components for compact widgets and plugin views. Use them for consistent spacing, text, status colours, and overflow behaviour. Import everything from the package root: The root is for primitives, dashboard components, hooks and theme utilities. Import AI elements from their stable subpaths so plugins only load the editor and rendering dependencies they use: Federated plugins that use AI elements should also import their Tailwind source entry after the base plugin stylesheet. The same rule applies to model-selection and context-editor components: Only import the specialized stylesheets for component families the plugin uses. Detailed props are canonical in the exported TypeScript types. The machine-readable catalogue (the data behind the tables below) ships as plain JSON at a stable subpath — read it directly: Worked, glass-styled example widgets ship on their own subpath — import them to preview, or copy one as a starting point: In the tables, primitive means an existing @sero-ai/ui primitive that is suitable for widgets. Composite means a dashboard component. - [Environment Doctor](/reference/environment-doctor.md): Environment Doctor checks the Sero host and the active profile. Use it when Sero starts but a provider, plugin, profile, runtime, or workspace does not work. If the desktop app cannot finish startup, use the command-line entry point. For symptom-based help, see Troubleshooting. - [Reference](/reference/index.md): Use reference pages when you need exact facts: support boundaries, runtime behavior, file locations, command syntax, plugin APIs, diagnostics, or security details. Reference pages are for lookup; use Guides when you want step-by-step task help. - [Known Limitations](/reference/known-limitations.md): For the current support matrix, see Support Scope. - [models.json Reference](/reference/models-json.md): models.json configures local and custom model providers for the active Sero profile. The file lives in the profile-scoped agent directory: For the default profile, that is usually ~/.sero-ui/agent/models.json. Sero reads and writes this file through the local models UI, then refreshes model availability. - [Orchestrator reference](/reference/orchestrator.md): Orchestrator is the built-in app with two independent execution modes: The Orchestrator app id is orchestrator. - [Output Optimizer](/reference/output-optimizer.md): The output optimizer is an optional built-in plugin. It reduces the shell output that reaches the model without deleting anything: complete output stays in capture files. Output optimisation is disabled for a new profile. Enable it in the plugin's settings surface. Disable it again to return to unmodified commands and results; no restart is needed. - [Plugin Author Quick Path](/reference/plugin-author-quick-path.md): Choose the page that matches your next task. Start with Plugin Quickstart if you are a new author. It gives you one complete journey from the maintained Notes example to an active local development session. Use an extension-only plugin when you need only Pi tools or commands. Add a UI when a user must interact with the plugin directly. Add a background runtime only for long-running work, such as watchers, recovery, or orchestration. - [Plugin End-to-End Example](/reference/plugin-end-to-end-example.md): The maintained Notes example shows all three plugin surfaces in one package. It uses monorepo workspace: and catalog: dependencies. Use it inside the Sero monorepo unless you port its complete manifest to published dependencies: source folderfile map and copy instructions Use this index to find the smallest relevant example. For an external repository, use the maintained Signal Desk plugin and its setup guide. - [Plugin Extension Points](/reference/plugin-extension-points.md): Extension points let a plugin add a component or a standard control to a location owned by Sero. The host owns the location, layout, lifecycle, and validation. A plugin cannot invent a new host surface. - [Plugin Quickstart](/reference/plugin-quickstart.md): Build an external plugin from the maintained Signal Desk plugin. Follow its setup and install guide. Its manifest uses published dependencies and can run outside this monorepo. The Notes example includes a React UI, a Pi extension, shared state, a background runtime, and a dashboard widget. It uses workspace: and catalog: dependencies and is for development in the Sero monorepo unless you port its complete manifest to published dependencies: The example is for a plugin inside the Sero monorepo: packages/templates/skills/sero-plugin/example/sero-notes-plugin/example file map and instructions For a separate repository, start with Signal Desk. Use Notes only when you need its additional surfaces. At the time of this documentation, @sero-ai/app-runtime is 0.4.0 and @sero-ai/plugin-vite is 0.1.1. Check the npm registry before you select versions for a new plugin. - [Plugins](/reference/plugins.md): A Sero plugin can provide Pi tools and commands, a React app, and an optional background runtime. It can also contribute components or standard controls to host-owned extension points. New authors should start with Plugin Quickstart. Users who only want to install an app should use App Store, Favorites, and Installed Plugins. - [Rooms reference](/reference/rooms.md): This page lists the runtime facts for Orchestrator Rooms. For the user task, see Create and run a Room. - [Security / Privacy](/reference/security-privacy.md): Sero is a local-first developer tool. It runs on your machine, stores profile state locally, and can optionally connect to remote services such as model providers, GitHub, plugin registries, Discord, Tailscale, or the Sero gateway. This page is practical guidance, not a claim of hardened isolation. Treat Sero like a powerful local automation environment: protect the profile directory, review what plugins and remote clients can reach, and report security issues privately. - [Sero CLI](/reference/sero-cli.md): sero-cli is Sero's workspace/session command surface. Agents call it as a tool, and operators can use the same syntax in Sero-aware terminal contexts. - [State and Folders](/reference/state-and-folders.md): Sero keeps profile data on the local machine. Use this map when you back up a profile, inspect state, or remove private data from a support report. - [Support Scope](/reference/support-scope.md): Use this page to check the platforms and runtimes that the current Sero release supports. - [Testing / Evals](/reference/testing-evals.md): Sero uses repository tests and promptfoo evals as separate quality signals. Not every suite runs for each pull request. Run real LLM evals only when their provider cost and credentials are intentional. - [Troubleshooting](/reference/troubleshooting.md): Start here when Sero will not launch, a workspace runtime is unavailable, or a preview does not work. First run Environment Doctor. It checks your platform, runtime, profile, providers, plugins, and workspace state, then reports which items passed, warned, or failed. Use this page by symptom. For exact platform support, see Support Scope. To choose or switch between Host, Apple Container, and Docker / Podman, see Choose a Workspace Runtime. - [Workflows reference](/reference/workflows.md): Reference for Orchestrator Workflows (app id orchestrator). For a task walkthrough with screenshots, see the Workflows guide. A Workflow is stored internally as a loop. The command API, event names, and storage paths keep that older term for compatibility. A Workflow stores a goal, a generated step plan, trigger settings, limits, and run history. Steps can run in order or at the same time. A Workflow completes only when a planned step reports completion. Orchestrator stores this state and manages scheduling, run locks, attempt and token limits, workspace isolation, and restart recovery. The Sero host controls the tools and permissions used by each step.