How it works & security

The bridgeCopy Anchor Link

Fusion's Python API only exists inside the Fusion process, and only on its main thread. fusionctl install adds a small add-in, FusionBridge, that starts with Fusion.

fusionctl ──HTTP + token──▶ FusionBridge (127.0.0.1) ──custom event──▶ Fusion API on the main thread

1. Each CLI command is one POST to http://127.0.0.1:18765/ with a JSON body such as {"op": "timeline"} and the token in the X-Fusion-Token header.
2. The add-in's HTTP server runs on a worker thread. It puts the request in a queue and fires a Fusion custom event, the one API call that is safe off the main thread.
3. Fusion calls the event handler on its main thread. The handler drains the queue, runs each operation and stores the result.
4. The worker thread sends the result back as JSON: {"ok": true, "data": …} or {"ok": false, "error": "<traceback>"}.

The operations live in bridge_ops.py. fusionctl reload re-imports that file inside Fusion, so changes to the operations need no restart; changes to FusionBridge.py need an add-in restart.

The worker waits up to 600 seconds for the main thread. While a modal dialog is open in Fusion the main thread does not process the event, so the request times out with timeout (modal dialog open in Fusion?).

The tokenCopy Anchor Link

• On its first start the add-in writes 48 random hex characters to ~/.config/fusionctl/token. The folder is created with mode 700 and the file with mode 600, readable only by your user.
• Every request must carry the token in X-Fusion-Token. A request without it, or with another value, gets 403 forbidden.
• The CLI reads the same file. If the two read different files (for example FUSIONCTL_CONFIG_DIR set for one and not the other), the CLI says the bridge rejected the token.

Loopback onlyCopy Anchor Link

The server binds to 127.0.0.1, so other machines on the network cannot connect. The port is 18765, or FUSIONCTL_PORT if set in Fusion's environment.

Browsers are refusedCopy Anchor Link

A web page in your browser can send requests to 127.0.0.1. Browsers always add an Origin header to such cross-site requests, and the CLI never sends one, so the bridge refuses every request that has an Origin header, whatever token it carries. A page you visit cannot drive Fusion, even if it guessed the token.

exec runs arbitrary PythonCopy Anchor Link

fusionctl exec and fusionctl run execute Python inside Fusion, as your user, with access to your files, your network and your Autodesk account's documents. That is the point of the tool, and it means:

• Read scripts from others before running them, as you would a shell script.
• Anyone who can read your token file can do the same. Keep ~/.config/fusionctl private.
• A coding agent that can run fusionctl can run any Python on your machine through it. Give it the same trust you give its shell access.

What leaves the MacCopy Anchor Link

Nothing, from fusionctl. The CLI talks only to 127.0.0.1. Fusion itself talks to Autodesk's services as it always does, for example when you save a document to a cloud project.