Sharing Profiles

Preferred sharing model

The recommended long-term model is to share a profile as a repo or package directory.

That keeps instructions, skills, MCP wrappers, and env examples together instead of forcing everything into one manifest.

Option 1 — Share a repo/package

Best for teams.

Recommended flow:

1. keep the profile in a repo or monorepo subtree
2. version all related assets next to the manifest
3. install or copy the profile locally
4. activate it in the local hub
5. apply it to the provider you want to use

Example template install:

Install a shared profile template

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

Then:

Activate and validate

agentstack profile activate team-default
agentstack doctor --profile-file ~/.agentstack/profiles/team-default/agentstack.yaml

Option 2 — Zero-config sync

Zero-config sync is still useful, but treat it as a convenience workflow, not the ideal canonical unit.

It stores profile state in a private GitHub Gist.

Set up zero-config sync

agentstack sync auth
agentstack sync init

Restore on another machine:

Restore from zero-config sync

agentstack sync auth
agentstack sync restore

Option 3 — Bundles

Bundles are good for one-time handoff or archival.

Export a bundle

agentstack bundle export \
  --profile-file ~/.agentstack/profiles/main/agentstack.yaml \
  --output ./my-profile.bundle.zip

Bundles are safe to share because they do not carry local secret values.

Team workflow recommendation

For most teams, this is the best current pattern:

• repo/package as the canonical source
• local AgentStack hub for activation/runtime
• apply for provider-native materialization
• sync/bundles only when they solve a real distribution problem

Security

Caution

Never commit plaintext secret values. Keep secret values out of the manifest, reference required env names from the profile/MCP wiring, and store actual values with agentstack secrets set.