Agent setup and guidance

Agent setup has one operating model: create a named agent, assign it to the right project, grant only the secrets it needs, and give the runtime a short-lived provisioning prompt. The prompt creates or rotates the Agent Key outside chat.

Choose a setup path

1. 1Use the CLI path when possibleThe CLI path is recommended because it stores the Agent Key in a named local profile, applies restrictive credential-file permissions, and can run commands through scopehold exec when a project .scopehold.json maps secrets to environment variables.
2. 2Keep API-only availableAPI-only setup remains supported for runtimes where the human chooses not to install the CLI or the runtime cannot install it. The agent redeems the prompt through the Runtime API and stores the returned Agent Key in its secure runtime store.
3. 3Use the assigned profileWhen the provisioning prompt names a ScopeHold CLI profile, the agent should use that exact profile with --profile unless the nearest .scopehold.json selects the same profile.

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 non-secret context such as apiUrl, profile, workspaceSlug, projectSlug, and environment-variable mappings.
• .scopehold.json must not store Agent Keys, provider secret values, OAuth credentials, database URLs, or credential payloads.
• When a command can receive secrets through environment variables, prefer scopehold exec so resolved values do not need to be written into project files.