State and Folders#

This page maps where Sero stores profile state, app state, auth files, and debug artifacts during the OSS alpha. Use it when troubleshooting, filing issues, or checking what should be redacted from screenshots and logs.

Sero is local-first, but local state can still be sensitive. Treat the active profile directory as private developer-machine data. For the user-facing setup flow, see Profiles and Onboarding.

Core path model#

Sero has one fixed root for the profile registry:

~/.sero-ui/profiles.json

Each profile points at an active profile root. In docs, that root is written as:

<SERO_HOME>

For the default profile, <SERO_HOME> is usually ~/.sero-ui/. Custom profiles can use another folder.

Inside the active profile, Sero uses an agent directory:

<SERO_HOME>/agent/

Sero sets PI_CODING_AGENT_DIR to this path so Pi uses Sero's profile-scoped agent directory instead of a separate non-Sero agent directory.

Important profile files#

Older notes may mention paths such as ~/.sero-ui/layout.json or ~/.sero-ui/github-auth.json. For current Sero alpha docs, prefer the profile-scoped <SERO_HOME>/agent/... paths above unless a page is explicitly describing legacy migration behavior.

Workspaces#

Sero keeps profile-owned workspaces under:

<SERO_HOME>/workspaces/

The built-in global workspace is:

<SERO_HOME>/workspaces/global/

Each real workspace directory can also contain:

<workspace>/.sero-workspace.json

That file stores workspace-level metadata and runtime configuration.

App state#

Sero apps and plugins can store state in one of two places.

Global app state#

Global-scoped apps use:

<SERO_HOME>/apps/<app-id>/state.json

For example, Scheduler/Reminders state is currently documented as:

<SERO_HOME>/apps/cron/state.json

Some plugin code can fall back to a workspace-relative .sero/apps/... path when running outside the normal Sero desktop environment. Public Sero docs should prefer the active-profile path when SERO_HOME is present.

Workspace app state#

Workspace-scoped app state lives inside the workspace:

<workspace>/.sero/apps/<app-id>/state.json

Examples from the current guides:

Git Integration also ignores its state folder with this pattern so the app state does not appear as an untracked repository change:

**/.sero/apps/git/

Memory storage#

Memory uses the global workspace under the active profile:

<SERO_HOME>/workspaces/global/MEMORY.md
<SERO_HOME>/workspaces/global/IDENTITY.md
<SERO_HOME>/workspaces/global/USER.md
<SERO_HOME>/workspaces/global/SCRATCHPAD.md
<SERO_HOME>/workspaces/global/memory/daily/YYYY-MM-DD.md

Memory debug logs live at:

<SERO_HOME>/debug/memory/

For the user-facing overview, see Memory.

Agent definitions and dashboard layout#

Subagent definitions live in:

<SERO_HOME>/agent/agents/

The default profile path is usually ~/.sero-ui/agent/agents/. Definitions can include private workflow instructions and model preferences, so redact them like prompt templates. For the exact format, see Agent Definitions.

Dashboard widget placement and instances are part of profile layout state:

<SERO_HOME>/agent/layout.json

See Dashboard and Widgets for the user workflow.

Local/custom model configuration#

Local and custom model providers are configured in:

<SERO_HOME>/agent/models.json

This file can include local endpoints, API keys, environment variable names, command-backed secret lookups, headers, model IDs, and model metadata. Treat it as sensitive when it contains private endpoints or credentials. For the exact supported schema, see models.json Reference.

Temporary runtime logs#

Some development/runtime logs are written outside the profile tree under /tmp/:

/tmp/sero-vite.log
/tmp/sero-electron.log
/tmp/sero-web-remote-watch.log
/tmp/sero-remote-<plugin>.log

These are local developer-machine artifacts, not durable profile state. They can still include private paths, errors, or workflow details, so redact before sharing.

What to redact before sharing#

Redact or avoid sharing raw copies of:

• ~/.sero-ui/profiles.json
• <SERO_HOME>/agent/auth.json
• <SERO_HOME>/agent/.env
• <SERO_HOME>/agent/github-auth.json
• <SERO_HOME>/agent/models.json
• <SERO_HOME>/agent/gateway-token
• <SERO_HOME>/agent/gateway-config.json
• <SERO_HOME>/agent/gateway-web-tokens.json
• <SERO_HOME>/agent/layout.json
• <SERO_HOME>/agent/workspaces.json
• <SERO_HOME>/agent/agents/
• memory files under <SERO_HOME>/workspaces/global/
• app state under <SERO_HOME>/apps/ or <workspace>/.sero/apps/
• debug/runtime logs that include private paths, prompts, tokens, or project data

Local vs remote behavior#

These are local/profile-scoped by default:

• profiles and profile registry
• agent settings/auth/plugins/prompts/skills
• workspaces and workspace metadata
• memory files and debug logs
• app state files

These may talk to remote systems, while still storing state locally:

• model/provider auth and API calls
• GitHub auth and repository access
• gateway remote-control clients when enabled
• plugin installs from npm, git, or local source paths
• App Store discovery and installed-plugin management
• third-party plugin integrations

For security posture and remote-control caveats, see Security / Privacy, Profiles and Onboarding, and Remote Control, Agent Definitions, and Dashboard and Widgets.