Quick start

01Requirements

• Bun 1.4
• Blender 5.2 (field tests used 5.2.2 LTS)
• An OpenAI-compatible AI provider URL and API key
• Optional: ima2-gen for AI images, the TDMCP bridge for TouchDesigner, Unreal Engine 5.8 with Unreal MCP

02Install and run

From the app folder of your checkout, install dependencies and start the server, then open the interface in your browser.

cd <checkout>/app
bun install --frozen-lockfile
bun run start
# open http://127.0.0.1:5178

03Connect your provider and Blender

Open Settings and enter your OpenAI-compatible provider address and API key. The default address is http://127.0.0.1:8318/v1. The key is stored on the server and API responses only show a masked value. Set the Blender path in Settings or with FACET_BLENDER.

04Run your first round

Create a new session, choose Blender, write a goal sentence and optionally add a reference image. Run the round to get real Blender renders from several models, side by side.

05Pick, continue, branch

Pick the result you like. The pick updates the program's playbook and the model and strategy Elo. Continue from it, or click an earlier result in the lineage to branch from there.

06AI images with ima2

The AI Image panel uses an ima2-gen server running on the same computer. Facetion does not start it for you, so run ima2 start first. The default address is http://127.0.0.1:3333; change it with FACET_IMA2_URL or in the panel. Only 127.0.0.1 and localhost are accepted.

07Other programs

TouchDesigner needs the TDMCP bridge and its config file; without a connection, the status is shown and rounds are blocked. Unreal, Cinema 4D, After Effects and ComfyUI each need the program, plugin or bridge installed and ready.

08Use Facetion from an AI agent (MCP)

Start the Facetion server first, then register this process in your MCP host. Tools include facet_status, facet_create_session, facet_start_round, facet_wait_round, facet_pick and facet_get_render.

{
  "command": "bun",
  "args": [
    "<checkout>/app/src/mcp/stdio.ts"
  ],
  "env": {
    "FACET_URL": "http://127.0.0.1:5178"
  }
}

09Environment variables

• FACET_PORT: server port (default 5178)
• FACET_DATA_DIR: data directory (default .facet-data in the checkout)
• FACET_BLENDER: path to Blender
• FACET_IMA2_URL: ima2 server address

10Good to know

• Generated Blender code runs in a separate process with a timeout and a static code guard. The static guard is not an operating-system sandbox.
• Model output quality varies from result to result. Check the vision scores, and look at the renders yourself.
• The interface and programs run on your computer, but AI calls go to the provider you configure.
• Model errors are recorded in the ledger and on the result cards.