Provider and Harness Onboarding

Provider and harness onboarding

Select a project scope and a real host tool before assigning work. A .SYSTEMX role or named BOT workspace is a coordination record. The provider's own login, account permissions, model and tool availability, data-handling terms, and runtime state must be checked in that provider. Agent 0 keeps the canonical WORK/TASKS.json task and accepts evidence after the run.

First-time sequence

1. Choose the containing .SYSTEMX or a registered .SYSTEMXP child. Record the objective and first accepted task. Read the selected release's START-HERE.md and first-time setup.
2. Review Agent1's security and access setup for owner/guest role, exact repository and environment, local secret source, .env names-only inventory, and rotation intent. Never paste secret values into a shared task, workbook, bot record, or assistant log.
3. Inspect the Agent 0 roster for local role, BOT, AUTOBOT, recorded CLI-channel, and access-decision references. A roster row does not prove an external account or permission.
4. Choose the actual lane below. Check its installed tool or connected app, active account, project access, data boundary, and supported actions. Record the result of a real test in the selected project's evidence, with the revision and provider identity needed to review it.
5. Delegate one bounded task, return the provider's artifact and actual readback, and have Agent 0 or the user decide acceptance. A provider's completed status alone does not close the canonical task.

Preview the local onboarding path

From the containing project directory, the selected-scope onboard views combine Agent1 question counts, Agent 0 roster counts, and a provider navigation catalog. They return no credential values and do not authenticate, install, or run a provider:

bash .SYSTEMX/SYSTEMX.sh onboard status
bash .SYSTEMX/SYSTEMX.sh onboard plan \
  --account-context personal --surface cli --provider codex-cli \
  --credential-consumer local-cli --credential-class new
bash .SYSTEMX/SYSTEMX.sh onboard plan \
  --account-context enterprise --surface sdk --provider codex-sdk \
  --credential-consumer server-application --credential-class new

Choose enterprise and the actual consumer when those are the facts. The plan response lists unresolved first-time questions and the selected provider's next checks. installedNameOnly means an executable name was found on this host; it does not establish login, model access, permission, or a safe task run. A null name-check result means the catalog has no safe executable probe, as with SDK/IDE/cloud surfaces or Cursor's generic agent command. The default output is readable text; use --format json for a machine-readable packet that includes installedNameOnly. With an explicitly selected existing dotenv file, --env-file uses Agent1's bounded names-only inventory on supported hosts. Windows fails closed for dotenv and answer-file operations in this beta. This view neither imports nor converts a .env value automatically. Do not place values in command arguments or project records. GitHub Actions secrets are for workflows in the selected repository; they cannot supply a local CLI, IDE, or .env through a symbolic link. Actions is disabled for dotSYSTEMX itself; check the selected project's Actions setting and actual secret consumer separately.

For a host that discovers project-root AGENTS.md, onboard bridge previews a short pointer to the selected .SYSTEMX/AGENTS.md. It creates the root pointer only after an explicit --apply --expected-sha256 SHA_FROM_PREVIEW using the preview's contentSha256. It preserves an existing root instruction file and does not configure Codex, Grok, Muse, or another provider. The preview works on Windows, but applying the bridge requires anchored directory handles and fails closed there in this beta. The bridge is for the outer .SYSTEMX project root, not a .SYSTEMXP child. Menu options 34, 35, and 36 open status, plan, and bridge preview respectively. The selected provider's own host discovery and trust rules still govern whether it reads that pointer.

Put a credential where its consumer reads it

Consumer selected in onboard plan	First-time check
Local CLI or VS Code extension	Prefer the provider's own login or an approved local OS credential store; verify the host account and project access. A GitHub Actions secret cannot fill either surface.
GitHub Actions	Check the selected repository's Actions setting, workflow, environment, scope, and actual consumer. dotSYSTEMX itself has Actions disabled and no workflow.
Codespaces, GitHub agents, or Dependabot	Use that product's own secret scope and verify the intended consumer there; a similarly named Actions secret is not interchangeable.
None	Record that no credential destination was selected; do not create or copy a key.

Use a newly issued credential by default when one is needed. Treat an existing key as test-only while the owner reviews rotation and downstream consumers. An existing .env can be inventoried by key names and previewed as a names-only .env.example through Agent1; the user then selects the actual store or provider destination for each key. The current guide does not bulk import, delete, rotate, or verify credential values. See Agent Beta, Agent1, and Agenda.

Choose one provider lane for each task

Lane	--provider ID	.SYSTEMX record	Execution and account boundary
Codex CLI	codex-cli	A reviewed Agent Y task-scoped handoff	The separately installed CLI and its login, selected model, repository permissions, and task run remain external.
Codex IDE extension	codex-ide	Agent 0 task and optional harness mapping	The host IDE supplies sign-in, tools, and permissions; the onboarding view does not install or authenticate it.
Native subagent	No provider ID; choose its actual host	Agent 0 task and a decision-only native-subagent Access Matrix row when needed	The host app/IDE supplies worker creation, tools, account, and permissions. A roster pattern is not a registered worker.
OpenAI DOT	openai-dot	Optional Agent Beta named dot workspace and canonical task reference	A DOT is a separately created cloud agent. The local workspace is an offline nonsecret reference; local computer access is an additional opt-in in the host.
xAI Grok Build CLI	grok-build	An optional manual external CLI lane	The grok executable has its own login and instruction discovery. Agent Y's configured adapter is not a reviewed Grok prompt-input contract, so this guide does not route Grok through it.
xAI Grok Bot	grok-bot	Optional Agent Beta named bot workspace and task reference	The persistent cloud Bot is separate from Grok Build CLI. The local record remains offline and does not connect the cloud Bot; xAI says Bots share a user's cloud computer, so do not assume isolation between them.
Meta Muse Code CLI	muse-code	An Agent Y handoff after the adapter and actual CLI are reviewed	The muse executable, login, model, account rights, and task run remain external.
Meta personal Muse	meta-muse	Optional Agent Beta named bot workspace and task reference	The personal product is separate from Muse Code CLI; the local record remains offline.
VS Code or another IDE harness	Select its provider where relevant	Selected project records plus a host-assigned worker identity	The IDE and extension supply execution and their own permission controls.
GitHub Copilot CLI	copilot-cli	A reviewed Agent Y task-scoped handoff	agent-y providers detects the installed name; GitHub login and access still require a host check.
Reviewed configured CLI	configured-cli	A task-scoped Agent Y configured adapter after an explicit absolute executable and argument/input contract are reviewed	Name discovery, login, tool permissions, and a safe noninteractive route are not supplied by this catalog ID.

Additional beta.2 discovery and host surfaces

The onboarding catalog may list a surface before an Agent Y execution adapter exists. These entries guide the user's next host check; they do not install, sign in, run, or connect a provider. agent-y providers lists its supported Agent Y CLI names separately from this broader onboarding catalog.

Surface	--provider ID	Route and boundary
Codex SDK	codex-sdk	Application-managed TypeScript/Python SDK integration through the developer's own application and credentials; no .SYSTEMX process or automatic SDK call.
Amazon Kiro CLI	kiro-cli	Formerly Amazon Q Developer CLI. Manual/discovery kiro-cli terminal entry; no Agent Y task-execution adapter. The generic kiro name can route to the IDE.
Amazon Kiro IDE	kiro-ide	Separate desktop IDE and its own sign-in, workspace, and permissions; no Agent Y process or VS Code extension claim.
Amazon Kiro web	kiro-web	Browser cloud sessions require host sign-in and repository authorization; Agent Beta holds an offline reference only.
AWS CLI	aws-cli	aws is a host account/infrastructure tool, separate from Kiro AI and outside Agent Y. Verify the selected profile and effective AWS identity.
Anthropic Claude Code	claude-code	Manual/discovery claude CLI; no Agent Y execution adapter.
OpenCode CLI	opencode-cli	Manual/discovery opencode CLI; check its actual V1/V2 binary, version, and provider account before use. No Agent Y adapter.
BLACKBOX CLI	blackbox-cli	Manual/discovery blackbox CLI; no Agent Y execution adapter.
Gemini CLI	gemini-cli	Manual/discovery gemini CLI; its own authentication source must be checked. No Agent Y adapter.
Cursor Agent	cursor-agent	Manual/discovery CLI whose current command is agent; a generic agent on PATH does not prove Cursor identity. Separate from the Cursor IDE host; no Agent Y adapter.
Aider	aider	Manual/discovery aider CLI; no Agent Y execution adapter. Review its model keys and automatic commit behavior; keep credentials out of command-line examples and logs.

The tagged provider catalog is the release baseline for these provider IDs, surfaces, and executable-name checks. The official setup links above describe the separate host tools.

The host checks are different for each row. Kiro's own authentication and kiro-cli version/kiro-cli whoami are separate from an AWS CLI profile and IAM Identity Center; an AWS account identity is not a Kiro coding-agent session. BLACKBOX's blackbox configure can select internal provider modes; they stay inside one BLACKBOX CLI lane here. An installed opencode name does not distinguish V1 from V2, and V2 may start its own background server. Gemini CLI authentication may use Google sign-in, an API key, or Vertex; its .gemini/.env behavior does not turn GitHub Actions secrets into local credentials. Keep Aider's API keys out of example command arguments and transcripts. All of these are external host behaviors, not effects of the read-only .SYSTEMX onboarding view.

The catalog is navigation and local discovery. A stored reference or matching executable name does not prove a live provider connection, account authority, or completed task.

OpenAI's Codex CLI, Codex IDE, and DOT getting started describe their distinct host setups. xAI documents Grok Build and Grok Bot separately. Meta documents Muse Code and its authentication choices; the personal Muse agent is a separate app/web/WhatsApp surface. The selected provider's own documentation remains the source for authentication and live permissions.

For a CLI lane, inspect its own login and instruction discovery before handing off a bounded task. Codex documents codex login status and repository-root AGENTS.md; Grok Build CLI documents grok login and grok inspect; Muse Code authentication requires the selected workspace's trust and sign-in or approved API-key path. These checks belong to the installed host. A local onboard or root roster response cannot substitute for them. An IDE extension and a CLI inside VS Code's integrated terminal are separate surfaces; choose vscode-extension or vscode-terminal in the plan accordingly.

Keep local records and external rights separate

The project-local launcher is bash .SYSTEMX/SYSTEMX.sh on macOS/Linux and pwsh -File .SYSTEMX/SYSTEMX.ps1 on Windows PowerShell. The installed systemx command manages versioned installation and routes project commands through run or projects; it is not an AI provider. The CLI and Tools guide distinguishes it from Agent Y's selected Codex/Copilot/Muse Code/configured CLI, GitHub CLI gh, IDE tools, and app-native workers.

agent-beta records a named BOT/DOT workspace without starting a provider. root roster reports selected-scope pointers without probing an account. agenda catalog shows stock reference settings and decision rules without selecting project options or granting rights. An Access Matrix reviewed-intent row records review intent, not an effective OS, repository, or provider permission. See Shared workspaces, clouds, and bots and Access Matrix for actual handoff and review boundaries. For an IDE or harness that owns a local read-only process, the Agent 0 toolchain I/O guide describes the fixed JSON-lines route and the separate host-registration gate.