Workflows: Manage cultivators
Browse the Kind catalog, enable a Cultivator for your tenant, configure its model and scope boundaries, and audit every run.
Prerequisites
cultivators:readto browse Kinds and read the run audit.cultivators:writeto create, configure, enable, or delete a binding.acaso_os:adminimplicitly satisfies both.
Without cultivators:read, the Cultivators nav item is hidden, and a direct visit to /cultivators shows a locked "Insufficient permissions" state. That gate is presentational; the API enforces the scope regardless, rejecting the underlying request with 403.
Browse the catalog
Open /cultivators. The page calls GET /v1/cultivators and renders one card per Kind available to your tenant, each showing its version, the events it reacts to, a Custom badge when it was built for you, and an at-a-glance health strip of recent run outcomes. The header toggle switches between Catalog and Run history.
Each card carries the Kind's state for your tenant: Available (uninstalled), Off (disabled), or Active (enabled).
Enable or disable a Kind
Flip the card's switch. The console creates the binding if none exists and sets enabled; dispatch then begins on the next matching ingest event. Flipping it off sets enabled to false, which stops dispatch on the next matching event — the worker reads the flag fresh each time — while keeping all of your configuration.
Note: Enabling and configuring are independent. A freshly enabled Kind runs with its defaults; open it to override the model or narrow its scopes.
Configure a binding
Open a Kind to reach its detail page, then click Configure to open the editor. The page also shows the Kind's triggers, its current configuration, and its access boundaries at a glance.
| Field | Effect |
|---|---|
| Activation | The same enabled toggle as the card. |
| Model | Override the Kind's default_model with any LiteLLM id. Blank uses the default. |
| Prompt append | Free text appended to the Kind's system prompt for your tenant's tone. |
| Pinned version | Pin the binding to a specific kind_version. Blank tracks the latest. |
| Scope boundaries | Per-tenant narrowing of the write and read ceilings. |
Saving calls POST /v1/cultivators for a new binding or PATCH /v1/cultivators/{kind} for an existing one.
/v1/cultivatorscurl -X POST "https://your-acaso.example.com/v1/cultivators" \
-H "Content-Type: application/json" \
-d '{"kind": "skill_extractor", "enabled": true, "model_override": "claude-haiku-4-5"}'External connections
A binding has no integrations to configure. If a Kind is an investigator — it declares requires_connections in code — the MCP servers it reaches are tenant-level Connections, not per-cultivator settings: one Composio account or internal MCP URL is registered once for the whole tenant, and every Kind that names it shares it.
Connections are a tenant asset managed out-of-band through the /v1/connections API (gated by connections:write), an engineer/ops surface rather than the management console. What a given Kind consumes — the connection name, the exact tools, and whether a missing connection skips or degrades the run — is fixed in PR-reviewed code and cannot be changed here. See Concepts: Cultivators for the full model.
Scope boundaries
The editor surfaces the two ceilings the Kind declares and lets you narrow each for your tenant. You can only ever narrow, never widen.
- Write ceilingthe scopes a proposal may carry. Narrowing it rejects any out-of-bounds proposal as
tenant_narrow_violation. - Read ceilingthe scopes the Cultivator runs under while reading DataHub.
Leaving a boundary untouched tracks the catalog. Clearing it to an empty set blocks everything, which the editor flags with a danger callout.
Warning: Narrowing a ceiling takes effect on the next run. Statements the Cultivator used to write may then be silently rejected and never reach memory. Watch the run audit after tightening a boundary.
Review run history
Switch the catalog header to Run history, or scroll to the Runs section on a Kind's page. The console calls GET /v1/cultivators/runs and lists runs newest-first with their status, the Kind, proposal counts, and timing. Filter by Kind, status, or a start date; the per-Kind page is pre-filtered to that Kind.
| Status | Meaning |
|---|---|
running | In flight. |
ok | Completed. Some proposals may still have been rejected. |
skipped | The Cultivator looked and chose not to act. Healthy. |
failed | An exception or timeout. The error field carries the reason. |
rejected_validation | Every proposal was rejected; nothing was written. |
Inspect a run
Click a row to open the run sheet. It shows the status and its meaning, the duration, the model used and any connections it reached, and:
- Committed statementsfor a successful run, each links straight to the statement on the Context page.
- Rejectionsgrouped by reason, each with the owner who can fix it and a hint. See Concepts: Cultivators for the reason taxonomy.
- Tracethe Langfuse trace id, copyable for deep debugging when tracing is enabled.
A raw-JSON disclosure at the bottom is the escape hatch for the full record.
Remove a binding
On a Kind's detail page, click Delete and type the Kind's name to confirm. The console calls DELETE /v1/cultivators/{kind}.
Deletion removes only your tenant's configuration. The Kind stays in the catalog, and the run history is deliberately preserved for audit.
Note: To stop a Cultivator without losing its configuration, disable it instead of deleting. Delete is for removing the binding entirely.