Kitsu

Clustta Studio can listen for task changes from Kitsu and apply them to linked Clustta projects. The setup has two parts:

1. A server administrator enables the always-on Kitsu listener and its encrypted credential store.
2. A Studio administrator connects Kitsu, links each Clustta project to its Kitsu project, and configures the project mappings.

No Kitsu webhook is required

Clustta connects to Kitsu's Socket.IO event stream at /events. The Clustta server initiates the connection, so you do not need to create a callback URL or expose a new inbound webhook endpoint.

What gets synchronized

The listener reacts to Kitsu task creation, updates, assignment, and unassignment events. For every event, Clustta fetches the current task from Kitsu and updates the matching mapped asset.

• Kitsu assignees are matched to Clustta collaborators by email address.
• Kitsu task statuses are translated through the project's status mappings.
• Only Kitsu projects and tasks already linked and mapped in Clustta are updated.
• Source files and checkpoint history remain in Clustta.

Clustta also performs a periodic reconciliation. This repairs state after a temporary network interruption or a missed real-time event.

How Kitsu tasks map to Clustta assets

In Kitsu, an entity such as a character or shot can have several tasks. For example, a character named Hero might have Modeling and Rigging tasks. Clustta uses these task types during the initial sync to choose:

• The Clustta asset type.
• The asset template and file extension.
• The output filename generated by the directory mapping.

Each task keeps its own integration mapping. The generated output filenames determine whether each task becomes a separate Clustta asset or a step on an asset shared with other tasks.

One asset per task

When Modeling and Rigging need separate working files, their task outputs can produce different paths:

Hero character
  > Modeling task > hero-modeling.blend
  > Rigging task  > hero-rigging.blend

Clustta creates two assets. Each has its own working file, checkpoints, status, and Kitsu task mapping.

Multiple tasks as steps on one asset

When Modeling and Rigging are stages of work on the same file, both task types can resolve to the same output:

Hero character
  > Modeling task > hero.blend
  > Rigging task  > hero.blend

Clustta creates hero.blend once and maps both Kitsu tasks to it. Modeling and Rigging are treated as steps on the shared Hero asset rather than as separate Clustta assets.

Mapping model	Task outputs	Result in Clustta
One asset per task	hero-modeling.blend and hero-rigging.blend	Two assets with separate working files
Multiple tasks as steps	Both tasks use hero.blend	One asset shared by both task steps

Clustta combines the task output with the parent collection, mapped template, and file extension. Tasks share an asset only when those values resolve to the same asset path.

Before you begin

You need:

• A running Kitsu/Zou instance reachable from the Clustta server.
• HTTPS in production. The server sends the service-account credentials again whenever it reconnects.
• A dedicated Kitsu service account with permission to read the projects, tasks, people, task types, and task statuses you want to synchronize.
• Matching email addresses for people who exist in both Kitsu and Clustta.
• Studio administrator access in Clustta.
• Project administrator access for every Clustta project you will link.
• A Clustta plan that includes integrations when using the hosted multi-tenant server.

Use the Kitsu server URL without a trailing /api, for example:

https://kitsu.example.com

Clustta adds the Kitsu API paths internally. Entering https://kitsu.example.com/api would produce an invalid /api/api/... request.

Part 1: Configure the Clustta server

The server stores the Kitsu service-account credentials encrypted and owns the persistent event connection. Complete this section before configuring the integration in the Studio UI.

1. Create the encryption key

Generate a random 32-byte key and encode it as base64:

openssl rand -base64 32

Keep this value in your secrets manager. Do not commit it to source control.

Keep the key stable

Changing or losing this key makes the saved integration credentials unreadable. If you rotate it, remove and configure the Kitsu integration again with the new key.

2. Set the server environment

Add the following values to the Clustta server environment:

# Required: base64-encoded 32-byte AES-256-GCM key
INTEGRATION_SECRET_KEY=<generated-key>

# Optional: how often Clustta rechecks all linked Kitsu tasks
INTEGRATION_RECONCILE_INTERVAL=30m

INTEGRATION_RECONCILE_INTERVAL accepts a Go duration such as 10m, 30m, or 1h. If omitted, it defaults to 30m.

For a container deployment, inject these values through your container secret or environment configuration. Avoid placing the encryption key directly in a checked-in Compose file.

3. Allow outbound connectivity

The Clustta server must be able to reach the Kitsu origin over:

• HTTPS for authentication and REST API requests.
• WebSocket/Socket.IO for the /events namespace and /socket.io/ transport path.

If Kitsu is behind a reverse proxy, make sure WebSocket upgrades are enabled for /socket.io/. No new inbound port is required on the Clustta server.

4. Restart and inspect the server

Restart the Clustta server after setting the environment variables. At startup, the server loads every enabled studio integration and starts one listener for each studio.

If INTEGRATION_SECRET_KEY is missing, the server logs that Studio integrations are disabled. If it is malformed, server startup fails with an invalid-key error.

Part 2: Configure Clustta Studio

This section creates the studio-wide listener configuration. The credentials entered here belong to the server-side service account, not an individual artist.

1. Connect the studio to Kitsu

1. In Clustta, select the studio you administer.
2. Open Studio Settings > Integrations.
3. Select Kitsu.
4. Enter the Kitsu server URL, service-account email, and password.
5. Select Save.

Saving performs a live Kitsu login. When it succeeds, the server encrypts the credentials, enables the integration, and starts the listener. The Integrations page should show Kitsu as Running.

You can use the toggle beside Kitsu to stop or restart the listener without deleting its configuration. Deleting the integration stops the listener and removes the stored credentials.

2. Connect your Clustta client to Kitsu

Project linking and mapping use a client-side Kitsu session in addition to the server service account.

1. Open Settings > Advanced > Integrations.
2. Select Connect Integration, then choose Kitsu.
3. Enter the same Kitsu API URL and a Kitsu account that can browse the target projects.
4. Select Connect.

This credential is stored for the current Clustta client. It is used to browse Kitsu projects and configure mappings; the server-side service account continues to receive events.

3. Link a Clustta project

Repeat these steps for every project that should receive Kitsu updates:

1. Open the Clustta project.
2. Open Project Settings > Advanced.
3. Select Link Integration.
4. Choose Kitsu, select the matching Kitsu project, and select Link Project.

The project link stores the Kitsu project ID. Renaming the project in either application does not break the link.

4. Configure project mappings

Still in Project Settings > Advanced, configure:

• Directory Mapping - defines where imported Kitsu entities are created in the Clustta collection tree. Its task outputs control whether task types generate separate filenames or share one filename.
• Asset Type Templates - maps each Kitsu task type to the Clustta asset template and file extension used for new assets.
• Status Mapping - maps each Clustta status to its Kitsu task status.

For example, mapping Modeling to <Asset>-modeling and Rigging to <Asset>-rigging produces separate assets. Mapping both task types to <Asset> produces one shared asset, with Modeling and Rigging represented as steps.

Run the Kitsu sync preview and initial sync after the mappings are ready. The initial sync creates the collection and asset mappings that the server listener uses to route later events.

Linking is not enough

The listener only updates a task after the Clustta project is linked and that Kitsu task has a corresponding asset mapping. Run the initial sync before testing live events.

Verify the integration

Use one mapped task and a collaborator who has the same email address in both systems:

1. Confirm Studio Settings > Integrations > Kitsu shows Running.
2. In Kitsu, assign the test task to that collaborator or change its status.
3. In Clustta, sync or refresh the linked project.
4. Confirm the mapped asset shows the new assignee or translated status.

For a full recovery test, temporarily disable Kitsu in Studio Settings, make a change in Kitsu, then enable the integration again. The startup reconciliation should apply the missed state.

How events reach a project

The complete path is:

Kitsu task event
  > Clustta server listener
  > fetch authoritative task state from the Kitsu REST API
  > find the Clustta project linked to the Kitsu project ID
  > find the asset mapped to the Kitsu task ID
  > resolve assignees by email and translate the status mapping
  > update the Clustta project database
  > deliver the change through normal Clustta project sync

Events for an unlinked Kitsu project or an unmapped task are ignored. Multiple events for the same task arriving close together are coalesced into a single task fetch.

Troubleshooting

The integration shows Error

Open the Kitsu configuration in Studio Settings > Integrations to see the latest listener error. Check the API URL, service-account credentials, TLS certificate, and whether the server can reach Kitsu's REST and Socket.IO endpoints.

The integration shows Stopped

Make sure the Kitsu toggle is enabled and INTEGRATION_SECRET_KEY is configured on the server. Saving or re-enabling the integration restarts its listener.

Login succeeds but live events do not arrive

Check the reverse proxy in front of Kitsu. It must pass WebSocket upgrades to /socket.io/, and the Clustta server must be able to establish the outbound connection.

An event arrives but no Clustta asset changes

Confirm that:

• The Clustta project is linked to the correct Kitsu project.
• The initial integration sync created an asset mapping for the task.
• The Kitsu task type is included in the project's mappings.
• The relevant Kitsu and Clustta statuses are mapped.

An assignee is missing

The Kitsu person's email must match a collaborator email in the Clustta project, ignoring case. Add the user to the project or correct the email, then wait for reconciliation or make another task change.

Changes appear after a delay

Real-time delivery may have been interrupted. The listener reconnects with backoff and the reconciliation job eventually repairs missed changes. Review server logs if this happens repeatedly.