Your First Profile

What a profile is today

Today, an AgentStack profile is centered on:

~/.agentstack/profiles/<name>/agentstack.yaml

That manifest is the current canonical source used by the hub runtime and provider adapters.

Current directory shape

At minimum, a profile looks like this:

~/.agentstack/profiles/my-profile/
  agentstack.yaml

As the profile-package pivot lands, related assets will increasingly live next to the manifest instead of only inside it.

A real current v3 example

version: 3

profile:
  name: my-profile
  description: Shared mobile engineering setup
  tags:
    - mobile
  created_at: 2026-03-08T00:00:00.000Z
  providers:
    codex:
      enabled: true
    claude:
      enabled: true
    opencode:
      enabled: false
    gemini:
      enabled: false
  instructions:
    global: |
      Keep responses concise.
    project_overrides:
      - ./AGENTS.md
  mcp_servers:
    - id: github
      transport: stdio
      command: npx
      args:
        - -y
        - '@modelcontextprotocol/server-github'
      env_refs:
        - GITHUB_TOKEN
      enabled: true
  skills:
    - id: core-review
      source: local
      path: ./skills/core-review.md
      enabled: true
  permissions:
    command_policy: on-request
  provider_overrides:
    codex:
      model: gpt-5

Create or bootstrap a profile

You can start in two ways:

agentstack init --profile my-profile

agentstack profile install \
  url:https://github.com/acme/agentstack-profiles \
  --profile my-profile

Activate it

agentstack profile activate my-profile

Activation prepares the hub runtime. It does not by itself write every provider-native config file.

Materialize a provider config

agentstack apply \
  --profile-file ~/.agentstack/profiles/my-profile/agentstack.yaml \
  --to claude

Validate it

agentstack doctor \
  --profile-file ~/.agentstack/profiles/my-profile/agentstack.yaml

Where this is heading

The long-term direction is to treat the profile as a package/repo and let agentstack.yaml act as the manifest.

See: