Epic: apify agent setup connects local coding agents to Apify plugins, skills, and MCP #1445

apify agent setup: one command that detects the coding agents installed on a machine and connects each one to Apify at the highest tier it supports. An Apify plugin where one exists, otherwise skills plus the Apify MCP server, otherwise MCP only, otherwise printed instructions. A hint after CLI install points people and agents at it.

Today the pieces exist but the user has to assemble them. apify mcp install <client> requires naming the client and holding a token, has no detection, and covers 7 clients. Skills come from apify help --skill, which the docs describe as a snapshot the user must reinstall on every CLI upgrade. Plugins ship from 15 per-platform repos generated by apify/apify-plugins-internal, and nothing in the CLI knows they exist.

Inspiration: stripe agent setup (detect, plan, prompt, apply, with a tiered fallback to downloaded skills) and Vercel's vercel agent init plus vercel skills.

Status (2026-10-19): community PR #1471 implements most of P0 together with the --non-interactive flag from #1451 (+1,825 lines). It has no reviews yet, and its Build and E2E checks fail. Suggested order: land #1451 on its own first, then rebase setup onto it.

Repositories

• apify/apify-cli: the apify agent command namespace, detection, plan, apply, state file, bundled catalog, and the post-install hint.
• apify/apify-plugins-internal: publish a catalog.json built from the platform configs that already drive the per-platform plugin sync.
• apify/agent-skills: drop the CLI command tables that duplicate apify help --skill.

Requirements

P0

• apify agent setup detects installed clients, proposes a plan, confirms once, and applies it.
• Tier ladder per client: plugin, then skills plus MCP, then MCP only, then manual instructions. The planner picks the highest tier the client supports and the catalog has an artifact for.
• Non-interactive mode and --json output when stdin is not a TTY, so a local agent can drive it headless. Non-interactive mode comes from the global resolver in Add a global --non-interactive flag #1451, not from a stdin check inside setup.
• Detect the agent running the current session, separately from the clients installed on the machine. Read AI_AGENT first, then the per-tool env vars. src/lib/hooks/telemetry/detectEnvironment.ts checks 9 variables today. Compared with @vercel/detect-agent, it misses AI_AGENT, CURSOR_TRACE_ID, CURSOR_EXTENSION_HOST_ROLE=agent-exec, CODEX_CI, OPENCODE_CLIENT, ANTIGRAVITY_AGENT, AUGMENT_AGENT, CLAUDE_CODE_IS_COWORK, REPL_ID, COPILOT_MODEL/COPILOT_ALLOW_ALL/COPILOT_GITHUB_TOKEN, and the /opt/.devin file. Setup should list the current agent's client first, and agent init uses the result to pick the file. Keep our own table rather than adding the dependency.
• --json returns one object: the per-client {client, tier, outcome} list, plus a top-level next array of commands to run when the user has to act (e.g. apify login). Vercel uses the same next pattern in util/agent-output.ts.
• Telemetry that can feed the success metrics below. Today cli_command records flag names only, so client, tier and outcome are invisible. Send them as properties of the setup run.
• Idempotent: an already-configured client reports already_configured and exits 0.
• State file next to auth.json recording what was installed, which client, and at which tier.
• Catalog bundled in the CLI (plugin ids, marketplaces, skills repo, MCP URL), so the command needs no network call.
• The MCP URL the CLI writes carries ?client=apify-cli, matching the ?client=claude+code+plugin tag the Claude plugin already uses.
• apify mcp install <client> stays as the lower-level primitive that setup calls.

P1

• apify agent status and apify agent uninstall, both reading the state file.
• catalog.json fetched from apify/apify-plugins-internal as a best-effort upgrade. A failed fetch falls back to the bundled copy and exits 0 with skipped: offline.
• Migration: when a client gains a plugin, remove the loose skills and the duplicate MCP entry the plugin replaces. Vercel does the same for Claude Code: it reads claude plugins list --json and moves users from vercel-plugin@vercel to vercel@claude-plugins-official (util/agent/auto-install-agentic.ts).
• Post-install hint with the same wording on every surface: bundle install, apify upgrade, npm postinstall, the apify help footer (the only surface Homebrew users see), README, docs/installation.md, and docs/agent-skill.md.
• Offer setup at the moment it's useful. After create or init succeeds in a TTY, ask once whether to connect the detected agent. Ask at most once a day, remember a "no", and never ask in non-interactive mode. Vercel does this after pull, env and project, storing lastPromptedAt in agent-preferences.json (same file as above).
• Sandbox detection (CI, non-TTY stdin, known sandbox env vars): print instructions instead of writing files, because the harness config lives outside the container.
• apify agent init writes an Apify block into the project's AGENTS.md or CLAUDE.md, wrapped in markers so it can be re-applied without touching the rest of the file, following vercel agent init. Pick the file from the detected agent: CLAUDE.md under Claude Code, AGENTS.md otherwise. That's Vercel's rule, between <!-- VERCEL BEST PRACTICES START/END --> markers (commands/agent/init.ts). Without a TTY, require --yes and name the flag in the error. Content comes from the agentsmd platform in apify/apify-plugins-internal. This replaces the hand-written apify help --skill pointer asked for in ts-crawlee-cheerio ships broken: optional deps stripped, CI needs an uncommitted lockfile actor-templates#941 (section 4) and Agent DX: three help strings route agents to the wrong tool #1424 (section 3).

P2

• Remaining clients from the catalog: Copilot, OpenCode, Devin, Kimi, Factory, Qoder, ZCode, Grok Build, DeepSeek Harness, and MS 365 Copilot.
• Generate the command list in skills/apify/SKILL.md from the command registry during pnpm run update-docs, the way docs/reference.md is already generated.
• CI check in apify/agent-skills that fails when a skill contains a CLI command table.

Success metrics

• Setup runs per week split by client, tier, and outcome (installed, already_configured, skipped: offline, error). Target: success rate above 90%.
• Share of new installs that run setup within 7 days.
• MCP sessions and Actor runs attributable to the ?client=apify-cli tag.
• Duplicate configurations reported by apify agent status (a plugin plus loose skills, or two Apify MCP entries), trending to zero after migration ships.

Key unknowns / to be discussed

• One umbrella Apify plugin per ecosystem, or one plugin per skill? apify/agent-skills publishes per skill today, the generated plugin repos publish one.
• Does setup run apify login when there is no token, or only print the hint? Stripe does not touch auth, Vercel provisions a key inline. Vercel can do that because its login is an OAuth device-code flow: it starts inline when an agent runs a command that needs auth, and prints "Please ask the user to manually visit the URL above" (commands/login/future.ts). Our Console login needs a callback to a localhost port, which fails in a sandbox or a remote agent. Until there is a device flow, setup should print apify login --token with a link to the token page, rather than start login itself.
• Default skills scope: project or user? Stripe and skills.sh default to project, the CLI docs say user.
• Keeping skills fresh without a plugin: npx skills add symlinks, a stub SKILL.md that loads current content on demand, or a hash-checked download.
• Do we apply to claude-plugins-official and openai-curated? Membership is what makes Stripe's plugin tier self-updating, and Apify is in neither. Vercel is in claude-plugins-official too, and its CLI turns on plugin auto-update when the user accepts the install.
• Unverified: whether the Apify MCP docs tools work fully anonymously, and how codex plugin add behaves for third-party git marketplaces.

References

• Prior art: stripe agent setup, vercel agent init, Vercel agent resources
• Plugin build pipeline: apify/apify-plugins-internal
• Vercel CLI source at c628be78: commands/agent/init.ts, commands/skills/index.ts (scans the framework and dependencies, then installs skills.sh skills with at least 100 installs), util/agent/auto-install-agentic.ts, packages/detect-agent
• Implementation PR: feat: add apify agent setup command with auto-detection and non-interactive flag (#1451) #1471. Depends on Add a global --non-interactive flag #1451.
• Related: feat: apify mcp install — one-command MCP setup for Claude, Cursor, Windsurf, and Copilot #1438 (detection ask this supersedes), AI Agent Integration — MCP install, Actor-as-tool, AI scaffolding, schema gen, diagnose #1443, Ship an agent skill (SKILL.md) for the Apify CLI #1232, Surface apify help --skill in the apify help output #1301
• Overlapping signposting work: Agent DX: three help strings route agents to the wrong tool #1424 (shares the apify help footer edit with the post-install hint above) and ts-crawlee-cheerio ships broken: optional deps stripped, CI needs an uncommitted lockfile actor-templates#941 (section 4)

Sub-issues to follow.