Set up task-start context

This optional setup lets a connected client make an initial bootstrap call at the beginning of each new task, with follow-up calls for permitted selection and discovery. Bootstrap reports the credential's personal or organization context, available ownership targets, usage capabilities, create rights, and Agent-definition selection. It does not connect the MCP server, install software, or grant access.

Before you start

Connect apistash using an API key or OAuth connection. The authenticated system tools setup, bootstrap, and agent_context do not depend on Tools, tool selections, or tool policies. To select or return an Agent, the credential also needs Agents (agents for an API key or mcp_agents for OAuth) plus the applicable Agent visibility controls. Tools and Agents are independent.

Do not put an API key, OAuth token, or client secret in a chat message. The setup request contains no secret.

Ask the current agent

In the client where apistash is connected, send this exact request:

"Set up apistash."

The local agent calls setup. The apistash server returns the canonical instruction and installation rules; the server and dashboard never write the client's files or settings. The local agent must inspect the client it is actually running in, choose the narrowest native scope that matches this connection and your intent, and ask before writing when more than one target or scope is plausible.

After verifying the saved state, it reports the client, target, scope, and one outcome:

• created — one managed instruction was added;
• updated — an older apistash-managed instruction alone was replaced;
• unchanged — the same or a newer managed version already existed; or
• not_installed — no writable native instruction target was available, so the agent showed the canonical instruction instead.

Optional guided content setup

After installing, repairing, or verifying the local instruction for a general setup request, the agent offers an optional conversation: “What will you mainly use apistash for?” You can decline and continue normally. A request only to repair or update the instruction does not start this interview unless you also ask for it.

If you opt in, the agent uses Bootstrap and its advertised tools to establish current access. It offers your own space only when available and Team choices only from the credential's bound Teams, explaining creation restrictions. A userless credential has no personal organization space. No available target is a blocker, not a reason to invent a personal or Team option.

The conversation covers your goals, technology and operating context, approval boundaries, and recurring roles. The agent inspects relevant content and proposes the smallest useful set of Agents, Prompts, and substantive Resources. It shows each draft or material change, name/path, content kind, and ownership target before asking you to confirm. An Agent definition alone is not permission to persist content. Material draft or target changes need renewed confirmation unless a specific standing instruction already covers them.

Writes use admitted management tools and their existing authorization and limits. Missing read access must be disclosed: creation needs explicit consent to the duplicate risk; updates need canonical editable data, including raw Prompt templates and arguments or Resource content with its matching version. Missing update inputs block the update and do not authorize a substitute create. Secrets, speculative facts, and empty placeholder Resources are excluded.

Expect separate created, updated/unchanged, skipped, and blocked outcomes for every confirmed item. A saved Resource intended for MCP use also needs a readability check; successful storage alone does not prove it is visible. Pending items mean partial completion. Assigning an Agent to the credential, publishing into the organization catalogue, and configuring connector secrets remain separate dashboard actions. See managing content for permission reporting and complete examples.

Native project scopes

The table lists the current documented project-local mechanisms for the clients in the supported-client guide. It does not guarantee that every client version lets an MCP-driven agent write that target. The local agent must inspect and verify the environment it is actually running in. This is also not permission to overwrite a file blindly: an existing file must keep every unrelated instruction, and a global target must not be chosen when the connection and request are project-specific.

Client	Native persistent instruction mechanism	Project-local scope and verification
Claude Desktop	Project instructions	Claude exposes these through Set project instructions, but a normal MCP tool call cannot edit that UI setting. The agent shows the managed block and reports not_installed; paste it into the intended Claude project and verify it there.
Cursor	Project Rules or AGENTS.md	Prefer an existing applicable rule mechanism. Cursor supports AGENTS.md at the project root and in subdirectories; nested files apply to that directory and its children and combine with parent instructions. Verify the rule under Customize → Rules.
Windsurf (Cascade)	Workspace Rules or AGENTS.md	A root AGENTS.md is always active for the workspace; a nested one is scoped to that directory. A dedicated workspace rule can live under .windsurf/rules/. Verify it in Customizations → Rules. This mechanism applies to the legacy Cascade agent.
OpenCode	AGENTS.md	OpenCode V2 combines every AGENTS.md from the current location upward with its global file instead of selecting only one. Put scoped guidance in the relevant directory, start a new session when an already-loaded nested file changes, and verify it is loaded.
Cline	Cline Rules or AGENTS.md	A dedicated project rule may live at .clinerules/apistash.md; a project AGENTS.md is also native. Verify the enabled rule in Cline's Rules panel.
Continue	Local Rules	Use a Markdown rule such as .continue/rules/apistash.md with a name in its frontmatter. Verify it in Continue's rules toolbar in Agent mode.
Gemini CLI	Hierarchical context file	Use the applicable project GEMINI.md. Verify the loaded path and content with /memory list and /memory show, then start a new task.
Custom agent (SDK)	Application-defined	The MCP SDK does not define persistent instructions. Unless your application provides a writable, verified mechanism, show the canonical instruction and report not_installed.

When a project already uses a shared AGENTS.md that several clients understand, one managed block in that file can be the narrowest target. Do not create a second client-specific copy merely because another supported file format exists.

The managed block

Version 2 is identified by apistash-bootstrap:

[apistash-managed-instruction id="apistash-bootstrap" version="2"]
At the start of each task, if `apistash/bootstrap` is available, make one initial call before substantive work. Always specify primary_agent. A primary starts with {"primary_agent":true}: use its credential-assigned Agent unless the user explicitly directs otherwise; if unassigned, choose a suitable definition or continue roleless. Report an unavailable assignment without substituting a role. A subagent must use primary_agent:false and the parent-provided agent_selection: "named" with agent:"<name>", "self" to choose its own suitable definition, or "none" to work without one. When delegating, explicitly supply that selection mode and any required name; never inherit the credential assignment. To load an allowed choice, call bootstrap again with the same primary_agent, agent_selection:"named", and agent:"<name>". A self-selecting subagent with no suitable definition must report to its direct parent and await its decision, not continue roleless; the parent may explicitly permit none, revise the delegation, or consult the user within its authority. Primary and self calls include an independent Agent catalog; other calls can request it with request_agent_catalog:true while keeping the same role arguments. Seeing the catalog does not permit changing role or delegating work. Follow-up selection and catalog calls are allowed. If the initial call is unavailable, denied, or fails, report any blocked delegated role requirement, continue only work independent of that requirement, and do not retry automatically.
[/apistash-managed-instruction]

The stable ID, not similar wording, identifies the managed unit. Repeating setup adds it once when absent, updates only an older matching unit, leaves the same or a newer version unchanged, and preserves all content around it. The local agent must read the result back before claiming success.

What happens on the next task

The primary starts with {"primary_agent":true}. It uses the credential-assigned definition unless the user explicitly directs otherwise. Without an assignment, it may select a suitable definition or continue without one. An unavailable assignment is reported, not replaced automatically.

When delegating, the parent explicitly supplies named with an exact name, self for delegated self-selection, or none for no definition. Subagents pass primary_agent:false and that agent_selection; they never inherit the credential assignment. A self-selecting subagent with no suitable definition reports to its direct parent and awaits a decision rather than continuing roleless. The parent can revise the delegation or consult the user within its authority.

The own-role result and visible Agent catalog are separate. Primaries and self-selecting subagents receive the catalog automatically; other subagents can request it through Bootstrap without Tools access and without changing their role. A permitted choice is loaded by a follow-up named call. Catalog visibility neither authorizes delegation nor a change of own role. See the Bootstrap reference for inputs and response states.

If the initial call is unavailable, denied, or fails, do not automatically retry. Report blocked delegated role requirements and continue only work independent of those requirements. Without Agents, Bootstrap still returns operating context, but both Agent delivery and discovery are disabled; explicit named selection and agent_context are denied.

The response also guides the agent to use relevant Resources and Prompts and propose saving stable knowledge with confirmation. It does not repeat onboarding. setup remains user-requested.

After a successful selection, conditional behavior is loaded with the qualified Agent name returned by bootstrap. Each agent_context call resolves the current active version; if a rename or behavior update makes the requested context unavailable, the agent continues without it or bootstraps again.

Agent behavior is guidance, not authority. It cannot add tools, scopes, team bindings, policies, permissions, or access to another organization.

Repair, update, or remove

Ask the agent to “repair the apistash task-start instruction” to focus only on repair or update. “Set up apistash.” also offers optional guided onboarding again, checking existing content first. To remove the setup, delete only the block with ID apistash-bootstrap from the native target. Removing it does not disconnect apistash or change the credential's centrally assigned Agent.

If setup does not install, follow the setup troubleshooting steps.