Agent setup and guidance

Agent setup starts with OAuth Connect. The agent runs scopehold connect, relays the verification URL and code, then a human approves the browser screen to select or create the agent identity, assign projects, grant only the secrets it needs, and choose the token lifetime.

Choose a setup path

1. 1Use OAuth Connect by defaultThe CLI prints the approval URL and code first, then stores the approved connection in a named local profile. Agents should relay the URL and code immediately, never silently wait for approval. For one-off commands, use inline --secret mappings. For repeated workflows, use .scopehold.json mappings.
2. 2Keep Agent Key provisioning advancedAgent Key provisioning remains available for CI, scripts, no-browser agents, or older CLI versions. Use it only when browser approval is not possible.
3. 3Use the assigned profileAgents should use the exact ScopeHold profile created by connect or provisioning. Project .scopehold.json files should stay agent-agnostic and should not commit one local agent profile by default.

ScopeHold Agent Guidance endpoint

Agents can fetch current guidance from https://api.scopehold.com/agent-guidance. The root endpoint returns the generic Markdown variant. Explicit variants are available with target=generic, target=claude, target=codex, or target=cursor.

generic

Plain Markdown guidance for any runtime or prompt-based agent.

claude

The same guidance packaged as SKILL.md-style content for runtimes that consume Claude-style skills.

codex

The same guidance packaged as SKILL.md-style content with Codex-oriented install hints.

cursor

The same guidance packaged as Cursor rule content for .cursor/rules/scopehold-agent.mdc or equivalent Cursor settings.

Project .scopehold.json

• .scopehold.json may store shared non-secret context such as apiUrl, workspaceSlug, projectSlug, and environment-variable mappings.
• .scopehold.json must not store Agent Keys, local CLI profile names, provider secret values, OAuth credentials, database URLs, or credential payloads.
• CLI profiles are local agent identity. Agents should use the assigned profile with --profile instead of committing one profile into project config.
• For one-off commands, use scopehold run --profile <assigned-profile> --secret VAR=provider/name[:field] -- <command>. Requires ScopeHold CLI 0.4.0 or newer; if --secret is unavailable, run npm install -g @scopehold/cli@latest.
• For repeated workflows, use .scopehold.json mappings and scopehold run --profile <assigned-profile> -- <command> (exec remains a supported alias) so resolved values do not need to be written into project files.
• When a project needs a new env-var mapping, agents should inspect inventory with the assigned profile, copy exact provider/name identifiers and supported field names from credentialFields, update only the non-secret mapping, and validate without printing secrets.
• API key mappings should specify the exact field needed. Use field: "value" for the key value and field: "referenceId" when inventory lists it and the provider also requires a key ID, client ID, account ID, or access key ID.