Profiles and Onboarding
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 <SERO_HOME>/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.
Fast path
- Launch Sero.
- Create a profile name such as
WorkorPersonal. - Optionally choose a custom storage location.
- If you already have another profile, choose whether to copy credentials and model preferences from it.
- Connect at least one model provider.
- Pick LOW, MED, and HIGH model defaults.
- Optionally connect GitHub.
- Open or create a workspace.
What a profile owns
The default profile usually uses ~/.sero-ui/ as <SERO_HOME>, so its agent directory is ~/.sero-ui/agent/. Sero intentionally uses this profile-scoped agent directory for Pi-backed agent state.
First run
On first launch, Sero asks for a profile name. If no profile exists, the first profile is created and activated. Existing installs are migrated by creating a Default profile that points at ~/.sero-ui/; existing data is not moved as part of that migration.
After the profile exists, onboarding checks whether Sero can use a model provider. If not, it opens provider authentication so you can sign in through OAuth where supported or add an API key. Then Sero asks you to choose LOW, MED, and HIGH model tiers with compatible thinking levels.
GitHub setup is optional during onboarding. Connect it if you want repository workflows such as clone, fetch, push, and pull-request-related actions.
Try a sample repair
After onboarding, open Dashboard and choose Try a sample repair. Sero prepares a disposable repository with one broken text helper and an existing check. Your other projects are untouched.
Review the selected providers and models before continuing. Model calls use your connected accounts and may incur charges. The $5 start cap is not a price estimate. Node.js and Git are required. Sero reuses verified installed tools or downloads shared tools automatically; your selected container runtime may also need its image. No sample package installation is needed. Sero keeps your selected workspace runtime.
Choose Prepare sample and approve access, then answer the access request.
Sero saves the faulty files in Git before the agent starts. The agent repairs
truncate.cjs and runs node --test repair.test.cjs. On the result page, use
See the checks, Open Git changes, and Open result to inspect the
passing check and changed source.
Use Stop on the work page to stop model work. If a provider fails, reconnect it and resume the same sample. If preparation fails, retry from Dashboard. Retries keep the same workspace and its files; reopening a stopped sample does not resume it automatically. The sample remains available for inspection.
Custom profile locations
When creating a profile, you can choose a custom storage folder. The profile name is independent from the folder name, and the selected folder becomes that profile's <SERO_HOME>.
Sero prevents obvious overlapping profile paths so one profile is not nested inside another existing profile by accident. Keep custom profile folders outside synced/shared locations unless you understand the privacy and conflict risks.
Switching profiles
Use the profile switcher in the title bar to choose another profile. Switching profiles updates the active profile in ~/.sero-ui/profiles.json and restarts Sero so process-level state, Chromium user data, provider auth, workspaces, sessions, and plugin state are reloaded from the new <SERO_HOME>.
If switching fails, the UI keeps the profile action visible and reports the restart-aware error. Relaunching Sero normally loads the active profile recorded in the registry.
Recovering profiles that are already on disk
If ~/.sero-ui/profiles.json is empty or was reset, Sero offers the profile
folders that still exist instead of making you start over.
- On the first-run screen, profiles found on this computer are listed above the create-profile form with their folder path and when each was last modified. Choose Open to register one at the folder it already occupies and restart into it.
- The profile switcher keeps listing profile folders that are not registered yet, so opening one never hides the others.
- Sero looks for these folders under
~/.sero-ui/profiles/, at the Sero root itself (~/.sero-ui/), and in the most recentprofiles.broken-*.jsonbackup besideprofiles.json.
Nothing is copied or moved when you open a profile. Sero registers the folder where it already is.
If the registry fails to load at startup, the recovery dialog offers Keep
existing profiles first. That choice rebuilds the registry from the profiles
the broken file still names and whose folders exist, and saves the broken file
as a profiles.broken-*.json backup. Reset stays available when nothing can be
kept.
Permanent deletion is offered only for a folder that a Sero record marks as Sero-managed. A recovered folder whose ownership no record proves is kept and is never offered for deletion.
Upgrading from 0.9
A 0.9 install kept everything in one folder and had no profile registry. On the first launch of 1.0, Sero adopts that folder as a Default profile, marks it as already set up, and opens it, so you do not see the setup screen again.
Nothing is copied or moved. Your profile stays in the folder it already occupied.
What carries over unchanged:
- the profile itself, and the folder it lives in
- sessions and their history
- memory files (
IDENTITY.md,USER.md) - Architect projects and other app state
- plugin state and settings
Before you upgrade, copy the whole ~/.sero-ui folder somewhere safe. Going
back to 0.9 after 1.0 has written to that folder is not supported, and a copy is
the only reliable way back.
If the upgraded profile does not open, the recovery steps above apply: Sero lists profile folders it finds on this computer rather than making you start over.
Container workspaces are experimental in 1.0. Host is the default and is the runtime the upgrade is verified against.
Copying credentials and model preferences
When you create a profile, Sero can copy credentials and model preferences from the active profile. It does not copy workspaces, sessions, memory, or general app state.
The copy flow can include these profile-agent files when they have meaningful content:
Only use this option when the new profile should trust the same providers, local endpoints, and credentials.
Removing profiles
Use the profile menu to manage an inactive profile:
- Retain files unregisters the profile and deletes its Sero-owned containers. It keeps all profile and workspace files.
- Delete files also permanently deletes the profile folder. Sero shows this option only for a folder that it created under its managed profiles directory.
Sero will not remove the only profile or the active profile. Switch to another profile first. The permanent option is never available for the main ~/.sero-ui folder, a custom folder, or a legacy profile with uncertain folder ownership.
Redaction checklist
Before sharing screenshots, logs, or support bundles, redact:
~/.sero-ui/profiles.json<SERO_HOME>/agent/auth.json<SERO_HOME>/agent/.env<SERO_HOME>/agent/github-auth.json- gateway token/config files
<SERO_HOME>/agent/models.jsonwhen it contains private endpoints, headers, or keys- workspace paths, prompts, memory files, and app state