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/...
├── workflows/...
├── agents/...
└── commands/...

Best practice: Keep the default profile unchanged and create custom profiles that inherit from it. This makes updating your base installation easier—you won't lose your customizations when updating. Most developers create a "main" custom profile (often called general, main, or custom) that inherits from default and contains their common tweaks and preferences.

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 (or from your main custom profile):

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

Profile configuration

Each profile has a profile-config.yml file:

inherits_from: default

exclude_inherited_files:
  - standards/backend/api.md

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

Profile inheritance can continue through multiple layers. For example, a common pattern is: rails-api → rails → general → default, where each profile only defines what's different from its parent.

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: general

This example uses general as the default profile—a common pattern where general is your main custom profile that inherits from default.

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.