kabaret.ipc

A plugin that packs a local FastAPI server, so any external tool such as DCCs, production trackers, etc. can talk to any Kabaret session.

Installation

uv add kabaret.ipc

Add the package to your existing virtual environment, and Kabaret loads the plugin entry point automatically. Requires Python 3.10 or newer.

Quick start

The server writes where it listens and how to authenticate in ~/.kabaret/ipc/server.json:

{"host": "127.0.0.1", "port": 51234, "token": "...", "pid": 12345}

The OS picks the port at each start, so you need to read that file to find the server. The token goes in an Authorization: Bearer <token> header on every request.

import json
from pathlib import Path

import requests

info = json.loads((Path.home() / ".kabaret" / "ipc" / "server.json").read_text())

response = requests.post(
    f"http://{info['host']}:{info['port']}/cmds/Flow/resolve_path",
    headers={"Authorization": f"Bearer {info['token']}"},
    json={"kwargs": {"oid": "/my_project/films"}},
)
print(response.json()["result"])

Usage

The first Kabaret session to start spawns the server on an open port, if none is already running. Every session then connects to it through a websocket.

The server stays up as long as one session is connected. When the last one disconnects, a 30sec cooldown starts and shuts the process down, unless a session shows up in the meantime.

If the server crashes or is closed by accident, sessions lose their websocket and try to relaunch it, retrying every two seconds.

Each run writes what it logs to its own file, ~/.kabaret/ipc/logs/ipc-{date}.log, alongside the console output. Only the five most recent are kept.

Routes

The full schema is served by FastAPI at http://{host}:{port}/docs.

• GET - /sessions:
  • Returns the active sessions, keyed by session uid: their name, the cluster used and, for GUI sessions, the current oid of the active view.
• POST - /cmds/{actor_name}/{cmd_name}
  • A single route to use any command from any loaded Actor, i.e. session.cmds.<actor_name>.<cmd_name>(*args, **kwargs).
  • Body: {"args": [...], "kwargs": {...}}, needed only if the command takes arguments.
  • session_uid is a query parameter. If it is left out and only one session is running, the server automatically uses it.
  • Returns {"result": ...}, or an error below.

/ws/{session_uid} is the websocket Kabaret sessions register on. It is internal: external tools use the HTTP routes.

Security

So that only trusted processes can reach it, the server generates a token and stores it in ~/.kabaret/ipc/server.json. Any utility needs to read that file to know how to use the local server.

The server only listens on 127.0.0.1 and the token is regenerated at each server start.

Resources

Kabaret IPC Blender Bridge

Support

Discord server