Frequently Asked Questions
SUMMARY
Quick answers about installation, supported environments, API keys, modules, and how to get help. If your question is not here, ask on the Telekinesis Discord or open an issue on the examples repository.
Getting Started
Which Python versions are supported?
Python 3.11 and 3.12 only. Earlier or newer versions are not currently supported. Check yours with python --version and create a clean conda environment if you need to switch.
Which operating systems are supported?
The core SDK works on Windows 11, Ubuntu 22.04, and macOS 13 (Ventura). Individual modules have their own platform notes:
- Synapse (robotics) - tested on all three platforms.
- Medulla (cameras / sensors) - tested primarily on Windows 11. See the supported cameras page for per-vendor driver requirements.
Do I need real hardware to try Telekinesis?
No. Most of the Quickstart starters run entirely offline against the kinematic model and visualize in Rerun. You only need hardware when you reach the Medulla camera examples or want to drive a real manipulator.
API Keys & Account
Is there a free tier?
Yes. Every new Telekinesis account comes with a free-tier credit allocation - no billing details required. Sign up at platform.telekinesis.ai.
Where do I store my API key?
Set it as the TELEKINESIS_API_KEY environment variable. The SDK reads it automatically. Never commit keys to git or hard-code them in scripts. See Step 2 of the Installation guide for shell-specific setup.
I lost my API key. How do I recover it?
You cannot recover the full key after the creation dialog is closed - only the first 4 and last 4 characters are visible afterward. Delete the lost key from the API Keys page and create a new one.
Modules & Architecture
What is the difference between Skills, Agents, Data Engine, and BabyROS?
| Layer | What it does |
|---|---|
| Skills | Modular building blocks - vision, robotics, hardware, learning. Composed into workflows. |
| Agents (Tzara) | VS Code extension that turns natural-language prompts into executable robot code by orchestrating Skills. |
| Data Engine | The memory layer - captures Skill executions and sensor data, turning them into reusable datasets. |
| BabyROS | Lightweight Pub/Sub and Client/Server messaging for distributed robotics on top of Zenoh. |
Which module should I install first?
Start with the base SDK: pip install telekinesis-ai. telekinesis-synapse, telekinesis-medulla with webcam support, telekinesis-datatypes, and babyROS are shipped with it. Then add the dependencies and module-specific extras only when you need them- See Step 4 of the Installation guide.
Do I have to install everything at once?
No - the library is modular. The base install gives you the SDK and default modules. Pull in extras as you go.
Installation Issues
pip install telekinesis-ai is failing.
Most install failures come from:
- Using an unsupported Python version - confirm with
python --version(must be 3.11 or 3.12). - Installing into the base environment instead of an isolated one - use
conda create -n telekinesis python=3.11first. - Network or proxy issues - retry, or pip install from a different network.
If it still fails, copy the full error and ask on Discord or open an issue.
telekinesis-urdfs clone is very slow.
That is expected. telekinesis-urdfs is a large repository with robot model data; the initial clone and wheel build can take several minutes. Do not interrupt it.
Import works but a specific Skill fails with a missing dependency.
You likely installed the base package without the module extras. Re-run with the appropriate extra, for example pip install "telekinesis-ai[medulla-ids]".
Running Skill Examples
Where can I find runnable examples?
The Telekinesis Skill Examples repository on GitHub - vision pipelines, robot motion demos, hardware capture, and full agentic workflows.
Rerun does not open when I run a Quickstart script.
The Quickstart scripts spawn Rerun with rr.init(..., spawn=True). Make sure rerun-sdk==0.31 is installed in the same environment as telekinesis-ai.
ModuleNotFoundError: No module named 'telekinesis'
Your telekinesis conda environment is not active in the current shell. Activate it before running anything:
conda activate telekinesisVerify the Python interpreter with which python (macOS/Linux) or where.exe python (Windows). It should point at your telekinesis environment, not the base interpreter.
I get 401 Unauthorized when I run a script.
TELEKINESIS_API_KEY is not set in the current shell. Verify with:
- macOS / Linux:
echo $TELEKINESIS_API_KEY - Windows PowerShell:
echo $env:TELEKINESIS_API_KEY
If the output is empty, re-export the key. If you set it in ~/.zshrc or ~/.bashrc, source the file again or open a new terminal. See Step 2 of the Installation guide.
Help & Community
Where do I ask questions?
- Discord - the fastest path for setup and conceptual questions: discord.gg/S5v8bYAnc6.
- GitHub Issues - for bugs in the examples repo: open an issue.
How do I report a bug in the SDK?
Open an issue on the examples repository with the commands you ran, the full error, your OS, and your Python version so we can reproduce it.