# Set up Groovy with an AI assistant

Groovy is a multi-agent harness, not a general-purpose Datagran account-creation API. First ask which path the user wants:

1. **Personal use:** register or sign in to the Groovy account portal, obtain an active license, download the current entitled connector, pair it to the account, and add chosen model-provider keys through the product's approved settings. The user completes registration, payment, and any provider consent.
2. **Developer or enterprise setup:** use the entitled source checkout and the Groovy CLI (`npm run groovy -- help`, then `doctor --json`) to identify required infrastructure, licensing, provider keys, and deployment checks. The checkout's `docs/ai-agent-setup.md` has the full self-hosting procedure. Do not assume the public source mirror is the current production checkout.

The public [setup page](/setup) is the browser entry point. A personal user does not need to create Vercel, Supabase, or Fly projects. Developer and enterprise hosting choices, billing, OAuth, and secret storage require explicit user decisions.

## Readiness sequence

1. Confirm the signed-in Groovy account, active plan or license, and intended workspace. A signed-in user can call `GET /api/agents/readiness` for structured account preflight evidence; an external harness key cannot call it.
2. Check that the chosen worker is attached to the intended device and workspace. The local connector must be online for local browser, file, terminal, and other connector-backed work. The readiness endpoint's `recent` heartbeat is only a three-minute observation, not a successful task probe.
3. Create or select a Mind and grant only the skills, integrations, and secrets it needs. A saved assignment does not prove the upstream provider works.
4. If the user chooses Datagran Memory or Datagran-backed sources, use [the Datagran guide](/ai/groovy-datagran.md). These are optional and need a Datagran account.
5. Review tool permissions and any approval request before execution. Check the returned task status and result. For a worker task, the session-only `GET /api/agents/tasks/{id}/diagnostics` gives a content-free status and safe next step. Do not equate `queued`, `running`, or a saved plan with completion, and inspect uncertain work before retrying.
6. For a website/widget conversation, use the [restricted external API](/openapi.json) only after an authorized owner creates an external Mind and a scoped key. This API is for conversations; it is not a worker administration shortcut.

Never ask for reusable credentials in chat. Put local secrets in an approved local env file or use the product's credential UI; hosted secrets belong in a platform secret manager. Do not publish secrets in source, docs, logs, screenshots, or PRs.

If `/api/agents/readiness` returns `503`, treat the account state as unknown and retry after the service recovers. Do not interpret an unavailable roster as zero workers. Datagran Memory's `savedConfiguration` likewise means a connection record was saved, not that the upstream provider is healthy.