Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
TETHER_HOMENoState folder. Default: ~/.tether.
TETHER_STATSNoSet to 0 to turn off the call log. The log stores counts and timings only, never code or output.
POLYPIZZA_KEYNoPoly Pizza key. Can also be put in ~/.tether/assets.json as polypizza_key.
RODIN_API_KEYNoHyper3D Rodin API key for generative 3D. Can also be read from ~/.tether/assets.json as rodin_key.
TETHER_ADDONSNoComma-separated add-ons the headless daemon enables, for example Sollumz. Default: none.
TETHER_BLENDERNoFull path of the Blender executable. Optional; Tether looks on PATH and in usual install folders first.
SKETCHFAB_TOKENNoSketchfab token. Can also be put in ~/.tether/assets.json as sketchfab_token.
TENCENT_SECRET_IDNoTencent Cloud secret ID for Hunyuan3D generative 3D. Can also be read from ~/.tether/assets.json as tencent_secret_id.
TENCENT_SECRET_KEYNoTencent Cloud secret key for Hunyuan3D generative 3D. Can also be read from ~/.tether/assets.json as tencent_secret_key.
TETHER_SCRIPT_DIRSNoExtra folders separated by ';' on Windows or ':' elsewhere, in which a relative file of run is looked up after cwd.

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

You send code to local apps in their own language (Blender for now). Order: status -> open if needed -> api_search -> run -> read the result back. • app = 'blender' or the selector from status, 'blender#pid' (the pid is required when several are open). • Do not write names and signatures from memory; verify them from the running version with api_search. • The namespace persists (functions, numbers, strings and lists live on) but is reset when a file loads: define a function once, then call it by name; do not resend the same code. Do not hold bpy objects (undo, file loads and mode changes make them stale and can crash Blender): keep the name and fetch bpy.data.objects[name] on every call. • The result is the result variable or the last expression. Do not dump big data: tether.brief(x). Output is cut at 8k characters (the full text is written to a file and its path is given). • Measure after writing (counts, file sizes, read-backs): not raising an error is not verification. An error may have changed the scene halfway; read the state before retrying. • Read matrix_world/bound_box only after tether.refresh(). • To understand the scene without writing code: scene (text: placement, size, topology, weights, GTA checks) and view (the default in the background is 4 angles; shading=wireframe/xray/texture; target=['Name'] frames). • No imports are needed in Blender (the ready names are in status.hint) and verified helpers are ready under tether: tether.select, tether.delete, tether.save, tether.backup, tether.mode, tether.edit, tether.export_sollumz. Use them instead of raw select_set/export: they raise with the reason instead of failing silently. • Instead of the old 'blender -b X.blend --python b.py -- a': run(file='b.py', args=['a'], cwd=..., blend='X.blend') on a background agent; narrow long output with grep='regex'.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}

Tools

Functions exposed to the LLM to take actions

NameDescription
statusA

Running apps: selector ('name#pid'), mode, version, busy or not, whether a modal operator is running, capabilities. Call this first.

runA

Runs code in the app's own language (Blender: Python; bpy, bmesh, mathutils ready). The namespace persists (reset=True clears it, fresh=True makes this call a one-off). Value: the last expression or result; print output and a line-numbered error trace come back too. Script (instead of 'blender -b --python x.py -- a b'): file = path (relative: looked up in cwd first, then in the server's working directory; the answer says which one ran), args = what follows '--', cwd, env = environment variables; it runs in a fresh namespace and cwd/env/sys.path are restored afterwards. Background Blender: blend = open that .blend first, clean = go back to the factory scene first (both refused in a windowed Blender). grep = regex: only the matching lines of the output are kept; if the output is cut the full text is written to a file and its path is given. timeout = seconds (code 60, script 300): when it expires the call returns but the job continues (status says 'busy'); its result is not returned.

api_searchA

Searches the app's API from the running version; use it before writing code. Blender: bpy.ops and bpy.types, open add-ons included. An exact name ('bpy.ops.mesh.primitive_cube_add') dumps the parameters and enum values.

sceneA

Scene report (read-only): the header has object/type counts, active, selected, mode; then fields per object (default: top-level objects, location+size+children+hidden). fields: location, size (world box including children), ground (ok/floating/below), rotation, scale, parent, children, hidden, details (faces/tris/verts, bones, light), materials, modifiers, animation; topology (quads/tris/ngons, boundary and non-manifold edges, loose vertices, poles); weights (vertices a deform bone does not move, bones without a vertex group); gta (Sollumz: UVMap 0, Color 1, sz_lods, shader, missing textures, unapplied transforms, .001 suffix); settings (file, engine, frames, resolution, camera, HDRI, units). Groups: placement, contents, health, all. root='Name': that object's hierarchy; query='text': the objects with it in their name; limit at most 200 lines.

viewA

One PNG of the scene + a caption line (which tile is which angle). width: pixels of the long side (of the whole image when combined). mode: viewport (windowed Blender: the user's view without the UI; background: the camera or an automatic frame), camera (at the render aspect), angles (frames the target from several directions; the background default), frames (an animation strip). shading: solid, texture, material, rendered (EEVEE), wireframe (edges over the surface), xray (transparent, bones visible). target: objects to frame, with their children (default everything visible; a big object such as a floor enlarges the frame). angles: at most 6 of front, back, left, right, top, bottom, iso or an [x, y, z] direction (default front, right, top, iso). distance: metres from the target to the eye. frames: frame numbers or frame_count (2-12, default 6); look: camera, an angle name or [x, y, z]; frames steps through the frames and returns to the old frame at the end. image: instead of the scene, 'Render Result', an open image name or a file path. area (windowed): 'window' = the whole window, 'NODE_EDITOR'/'OUTLINER'... = a screenshot of that area (the splash window may cover it); it cannot be combined with the other options. Temporary settings are restored.

asset_searchA

Searches ready-made 3D assets on the internet: models, PBR textures, HDRIs. source: all (default, in parallel), polyhaven (all CC0, no key), ambientcg (textures/hdris, CC0), sketchfab (models; a token is needed to download), polypizza (low-poly models; an API key). The query is English ('couch' also finds sofa). kind: model, texture, hdri. license: CC0 only by default; 'cc0,by' also brings CC-BY (attribution required). category: a text filter. polyhaven only: attrs={'weather': 'clear'} (hdri), min_size_m (the real size of a texture; 2+ for floors and walls). max_faces: polygon cap (polyhaven, sketchfab). animated: sketchfab, polypizza. previews=N (at most 6): small images of the first N results as one numbered image. Line: source id | kind | name | category | faces | size (m) | highest resolution | license | author. Pass the id to asset_import.

asset_importA

Downloads a found asset and brings it into Blender (the download happens on this computer, from allow-listed hosts, with a size cap, into a cache; it is not downloaded twice). model: arrives under a root empty; target_size = the largest dimension in metres (chair 1.0, car 4.5, cup 0.12; sketchfab/polypizza arrive at an arbitrary scale, always give it); snap_to_ground puts the centre of the base at location ([x, y, z], default 0,0,0). texture: a Principled material named 'source_id' (kept even if it is outside the scene); apply_to=['Object'] replaces those meshes' material (warns if there are no UVs). hdri: assigned as a new world (the old one is kept). resolution: 1k (default), 2k, 4k, 8k; format: model gltf/fbx, texture jpg/png, hdri hdr/exr. accept_license: take a non-CC0 asset knowingly. Returns: bounding box, tris, materials, file, license; look at it with view afterwards. The root gets the properties asset_source/asset_license/asset_attribution. A generated model: source='rodin' or 'hunyuan', id = the job from generate_start (it must be done: see generate_status); target_size is advisable.

generate_startA

Starts generating a 3D model from text or pictures at a paid provider: rodin (Hyper3D Rodin; RODIN_API_KEY) or hunyuan (Tencent Hunyuan3D Pro; TENCENT_SECRET_ID and TENCENT_SECRET_KEY). Each job spends the provider's credits, so without accept_cost=True NOTHING is sent: the answer shows the job and its cost; ask the user before passing accept_cost=True. prompt (English or Chinese) or images (local .jpg/.png/.webp paths; rodin up to 5, hunyuan 1, and hunyuan takes a prompt or an image, not both). rodin: tier (default Gen-2.5-Low; Gen-2.5-Medium/High need a full API plan). hunyuan: pbr (PBR materials, +credits), face_count (3000 to 1500000, +credits). It takes minutes: poll generate_status, then asset_import(source=provider, id=job). Models are generated in the provider's cloud; the license is the provider's terms.

generate_statusA

Asks the provider once how a generate_start job is doing: waiting, running, done or failed. When it is done the model is downloaded (once, into the cache); then bring it into Blender with asset_import(source='rodin' or 'hunyuan', id=job, target_size=metres). Poll no more often than every 10 seconds.

openA

Starts the app outside the caller's container and waits for its agent. Returns: selector, pid, mode, version, startup_s (seconds). Blender: background=True is a headless daemon: the factory scene (cube, camera, light), no user settings and no add-ons unless addons=['Name', ...] (add-on module names) or the TETHER_ADDONS environment variable are given; it closes after 30 minutes idle or when this session ends. background=False is windowed: it starts with the user's settings and the splash window shows. file = a .blend to load at startup; clean = start without user settings.

closeA

Closes only a background agent. The user closes a windowed Blender; close a window you opened with open only by calling bpy.ops.wm.quit_blender() through run (the connection drops, which is not counted as an error).

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A4/5.0

Scored across 11 tools

Disambiguation4/5

Most tools have clearly distinct purposes: open/close manage the session, run executes code, api_search looks up API, scene/view inspect, and asset_search/asset_import form a clean search-then-import pair. The only mild friction is the generic name 'status' (running apps) sitting beside 'generate_status' (generation job) and 'scene'/'view', which all report some kind of state; descriptions resolve it but the bare names could cause a first-glance misselection.

Naming Consistency3/5

All names are lowercase snake_case, which is good, but they mix at least three conventions: verb_noun (asset_search, asset_import, generate_start, generate_status, api_search), bare verbs (open, close, run), and bare nouns (status, scene, view). The generate_* and asset_* prefixes give helpful grouping, but the overall set is not a single predictable pattern.

Tool Count5/5

Eleven tools is well within the sweet spot for a rich Blender control server. Each tool occupies a distinct role (lifecycle, code execution, inspection, asset acquisition, AI generation) and none feels redundant or bolted on.

Completeness4/5

The surface covers session lifecycle (open/close/status), code execution and API discovery (run/api_search), visual and textual inspection (view/scene), asset search/import, and paid model generation with polling — a coherent end-to-end workflow. Minor gaps are that saving/exporting, undo, and closing a windowed Blender are not exposed as first-class tools (the latter is explicitly punted to run), though run provides a universal escape hatch.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues