Newcomer Onboarding

This guide is written for someone who has never used AgentStack before.

It describes the current working flow, not an imagined future flow.

1. Install your provider first

AgentStack does not currently install every provider for you.

Install the tool you want to use first, for example:

You currently have two realistic ways to start:

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

agentstack init --profile main

init now auto-activates the profile it creates or restores.

or import from a tool you already use:

agentstack import \
  --from codex \
  --source ~/.codex/config.toml \
  --profile-file ~/.agentstack/profiles/main/agentstack.yaml

agentstack profile activate mobile-default

This switches the active profile and prepares the current hub runtime.

If you came through agentstack init, this step is already done for the profile that init produced.

agentstack doctor \
  --profile-file ~/.agentstack/profiles/mobile-default/agentstack.yaml

Doctor is the fastest way to catch missing env refs, invalid profile structure, or broken hub state.

If you want to use Codex:

agentstack apply \
  --profile-file ~/.agentstack/profiles/mobile-default/agentstack.yaml \
  --to codex

If you want to use Claude Code:

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

Remember the current split:

Those two steps are related, but they are not the same command today.

If your profile references MCP env refs such as GITHUB_TOKEN, store those values before expecting the MCPs to work.

agentstack secrets set GITHUB_TOKEN ghp_xxx --backend darwin-keychain

What usually works well today:

What is still evolving: