Groovy is the base agent. Your product becomes a capability inside it. No forks, no separate chatbots, no custom UIs. You define typed tools. Groovy orchestrates, validates, executes, and tracks everything.
Works for SaaS APIs, CLIs, on-prem products, and anything with an HTTP endpoint or a command-line interface.
Groovy stays the single agent the user talks to. Integrations add new tools and behaviors without creating separate agents, dashboards, or chatbots.
Your product does not become its own AI assistant. It becomes a set of typed tools inside Groovy. The user never has to choose which agent to talk to.
Skills are natural language instructions that tell Groovy when and how to use your tools. Tools are the actual executable actions with validated schemas.
Routing, input validation, approval checks, execution, error handling, audit logging, usage metering, and response formatting are all handled by Groovy.
From your product to a Groovy capability in minutes, not months.
Create a JSON manifest that declares your tools. Each tool has a slug, description, input schema (JSON Schema), risk level, auth requirements, and an action that tells Groovy how to execute it.
{
"schemaVersion": 1,
"displayName": "AcmeOps",
"capabilityTags": ["incidents", "ops"],
"skillInstructions": "Use for incident
and deployment workflows.",
"tools": [{
"slug": "create_incident",
"name": "Create Incident",
"description": "Create a new incident",
"riskLevel": "write",
"authScope": "end_user",
"inputSchema": {
"type": "object",
"properties": {
"title": { "type": "string" },
"severity": {
"type": "string",
"enum": ["low", "medium", "high"]
}
},
"required": ["title", "severity"]
},
"action": {
"kind": "http_action",
"method": "POST",
"url": "{{connection.base_url}}/incidents",
"headers": {
"Authorization":
"Bearer {{connection.api_token}}"
},
"body": {
"title": "{{title}}",
"severity": "{{severity}}"
}
}
}]
}Install the extension, choose a runtime, configure auth (per-user or org-wide), set approval policies for destructive actions, and optionally assign a customer runner for CLI/on-prem execution.
// 1. Create the extension
POST /api/extensions
{ slug, name, manifest, activate: true }
// 2. Install it
POST /api/extensions/{id}/install
{
"approvalPolicy": {
"requireApprovalForRiskLevels":
["destructive", "privileged"]
}
}
// 3. Save connection auth
POST /api/extensions/{id}/connection
{
"config": {
"base_url": "https://api.acme.com"
},
"secrets": {
"api_token": "sk-acme-..."
}
}
// secrets are encrypted with AES-256-GCM
// never returned to the clientUsers don't interact with your integration directly. They talk to Groovy in natural language. Groovy picks the right tool, validates inputs against your schema, checks approvals, executes, and responds.
User: "Create a high severity incident
for checkout failures and assign
it to the on-call team"
Groovy sees:
→ AcmeOps integration installed
→ ext_acmeops_create_incident available
→ riskLevel: write (no approval needed)
→ authScope: end_user (connected)
Groovy executes:
POST https://api.acme.com/incidents
{ title: "Checkout failures",
severity: "high" }
Result:
✓ Incident INC-4821 created
✓ 1.2s · Audited · MeteredEvery integration chooses where its tools execute. Three runtime targets cover SaaS, on-prem, and local-device use cases.
For SaaS APIs and hosted webhooks
"action": {
"kind": "http_action",
"method": "POST",
"url": "{{connection.base_url}}/api/v2/incidents",
"headers": { "Authorization": "Bearer {{connection.api_token}}" },
"body": { "title": "{{title}}", "severity": "{{severity}}" },
"timeoutMs": 15000
}For CLIs, on-prem, and private networks
"action": {
"kind": "cli_action",
"argvTemplate": [
"acmectl", "incident", "create",
"--title", "{{title}}",
"--severity", "{{severity}}",
"--json"
],
"cwd": "/opt/acme",
"timeoutMs": 30000,
"maxOutputChars": 8000
}For local-device and personal automations
"action": {
"kind": "connector_action",
"connectorType": "terminal_exec",
"params": {
"command": "acme status --json --env {{env}}"
}
}Not bolted on later. Every extension tool call goes through permissions, approvals, audit, and metering from day one.
Immutable log of who triggered what action, through what identity, with what approval outcome. Every tool call, every time.
Track duration, bytes in/out, cost, runtime target, adapter type, approval state, and error codes per tool call.
Full execution traces with request/response payloads, error messages, and timing for debugging and performance analysis.
Product analytics for adoption tracking: which integrations are used, how often, by whom, and which tools are most popular.
Every tool is classified as read, write, destructive, or privileged. Risk drives approval policy and branch-controller behavior.
Require human approval for specific risk levels. Per-install, per-tool granularity. Blocked tools return structured approval requests.
Four auth scopes: none, end_user, shared_org, service_identity. Each tool declares what it needs. Connections match scope.
Connection secrets encrypted with AES-256-GCM before storage. Never returned to the client. Decrypted server-side at execution time only.
An Extension Pack is a versioned JSON manifest with five parts. No custom UI code, no server infrastructure (unless you use a runner).
{{...}}Reference user arguments, connection secrets, and runtime context in URLs, headers, query params, request bodies, and CLI argv templates.
args.*User-provided tool arguments (from Groovy's tool call)connection.*Merged config + decrypted secrets from the saved connectionruntime.user_idCurrent Groovy user IDruntime.trace_idCurrent execution trace IDruntime.session_idCurrent orchestrator session IDruntime.turn_idCurrent turn ID (for billing aggregation)runtime.device_idPaired device/connector ID (if present)// HTTP action
"url": "{{connection.base_url}}/api/v2/incidents"
"headers": {
"Authorization": "Bearer {{connection.api_token}}",
"X-Request-ID": "{{runtime.trace_id}}"
}
"body": {
"title": "{{title}}",
"assignee": "{{assignee}}"
}
// CLI action
"argvTemplate": [
"acmectl", "incident", "create",
"--title", "{{title}}",
"--severity", "{{severity}}",
"--team", "{{connection.default_team}}"
]
// If the entire value is a single {{...}},
// the resolved type is preserved (not stringified).
// "body": "{{args}}" → passes the full object.Any product with an API or CLI can become a Groovy integration. Here are the patterns we see most.
Create, update, escalate, and resolve incidents from natural language. Map severity, assign on-call, post updates — all through Groovy.
"Create a P1 for payment failures and page the on-call"
Rotate API keys, check service health, trigger deploys, manage feature flags. CLI runner executes approved commands in your infra.
"Rotate the staging API key for Team Red"
Look up contacts, create deals, log activities, update pipeline stages. Groovy becomes the natural-language interface for your sales stack.
"Add a note to the Acme deal that they want Q3 pricing"
Query dashboards, fetch metrics, generate summaries. Read-only tools with no approval required — fast and safe.
"What was our conversion rate last week vs the week before?"
User management, permission changes, config updates. Destructive actions require approval. Audit log captures who did what.
"Disable the staging account for user@example.com"
Trigger ETL jobs, check pipeline status, query data warehouses. Groovy wraps your data CLI or API with typed schemas.
"Run the daily revenue sync and tell me when it finishes"
From enterprise product to audited result in a single Groovy conversation turn.
Developers build integrations. Admins install and govern them. End users just talk to Groovy.
Every operation is an API call. Build dashboards, CI/CD hooks, or CLI tools on top.
# Extensions
GET /api/extensions List extensions
POST /api/extensions Create or update extension + version
# Installation
POST /api/extensions/{id}/install Install or update installation
# Connections
GET /api/extensions/{id}/connection List connections for an extension
POST /api/extensions/{id}/connection Create or update connection (secrets encrypted)
# Runners
GET /api/extensions/runners List runners
POST /api/extensions/runners Register or update a runner
POST /api/extensions/runners/{id}/heartbeat Runner liveness heartbeat (bearer auth supported)
# All endpoints use standard Supabase cookie auth.
# Runner heartbeat also supports bearer token auth for machine-to-machine.Ship an integration in hours. Your users get a capability they can talk to in natural language.