Profiles

Profiles are complete configuration packages for Agent OS containing standards, roles, workflows, and templates. Switch profiles to adapt Agent OS to different tech stacks or project types.

This page covers:

• The default profile
• When to use multiple profiles
• Profile inheritance
• Profile configuration
• Creating custom profiles
• Using profiles
• Switching profiles on a project

The default profile

Every Agent OS base installation starts with a default profile—your foundation for standards and patterns used across most projects.

~/agent-os/profiles/default/
├── standards/
│   ├── global/...
│   ├── backend/...
│   ├── frontend/...
│   └── testing/...
├── roles/
│   ├── implementers.yml
│   └── verifiers.yml
├── workflows/...
├── agents/...
└── commands/...

For many developers, the single default profile is enough. Customize it to match your preferences so that these apply to every project installation.

When to use multiple profiles

Create additional profiles when you:

• Switch between tech stacks: For example, Rails projects vs Node.js projects
• Have different project types: For example, web apps vs CLI tools vs mobile apps
• Work with different teams: Where each team has its own conventions
• Manage client projects: Different clients, different standards

Profile inheritance

Instead of duplicating everything for each profile, inherit from a parent profile and override only what's different.

How inheritance works

1. Start with a parent (usually default)
2. Inherit all standards, roles, and workflows
3. Override specific files with your customizations
4. Add new elements unique to this profile

Example

Creating a django-api profile that inherits from default (see also Standards):

In ~/agent-os/profiles/django-api/profile-config.yml:

inherits_from: default

Only override what's different:

~/agent-os/profiles/django-api/
├── profile-config.yml
├── standards/
│   └── backend/
│       ├── django-models.md
│       └── django-views.md
└── roles/
    └── implementers.yml

Profile configuration

Each profile has a profile-config.yml file:

inherits_from: default

exclude_inherited_files:
  - standards/backend/api.md
  - roles/implementers.yml

You can use the exclude_inherited_files section to exclude specific files from being inherited from the parent profile.

Profile inheritance can continue to the next parent profile until there are no more parent profiles to inherit from. For example, the rails-api profile can inherit from the from the rails profile, which inherits from the default profile.

If you set inherits_from to false, then this profile will not inherit from any parent profile.

Creating custom profiles

You can create a new profile using the create-profile.sh script.

~/agent-os/scripts/create-profile.sh

This script creates the profile directory structure, sets up the configuration file, establishes inheritance, and creates placeholder directories. You can then copy and edit files from the default (or other) profile that you want to override in this new profile.

Using profiles

To set the default profile used on all project installations, set this in your base installation's ~/agent-os/config.yml:

default_profile: react

To install Agent OS into a project using a different profile than your default, use the --profile flag:

~/agent-os/scripts/project-install.sh --profile django-api

See installation guide for details.

Switching profiles on a project

If your project installation initially used one profile, but you want to switch to a different profile, you can re-run the project installation script with the new profile:

~/agent-os/scripts/project-install.sh --profile react-app

This will detect your project's current installation and configuration and present you with a list of options for how you wish to proceed with the update, including re-installing Agent OS with the new profile.

The same process applies if you've updated your base installation's profile and need to push those updates to your project installation. Again, just re-run the project installation script and ensure the correct profile is specified.

For more details, see the project update guide.