Skip to content

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? ​

The SDK (telekinesis-ai) supports Python 3.11 and 3.12. Companion packages differ; see the Compatibility note on each install page.

Check yours with python --version. If you need to switch, create a fresh environment as shown in Step 1 of the Quickstart.

Which operating systems are supported? ​

The core SDK works on Windows 11, Ubuntu 22.04, and macOS 13 (Ventura). Some modules have narrower support; see the Compatibility note on each install page.

Do I need real hardware to try Telekinesis? ​

No. The Quickstart examples run entirely in software against the robot's 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 Quickstart 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? ​

LayerWhat it does
SkillsModels & algorithms - 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 EngineThe memory layer - captures Skill executions and sensor data, turning them into reusable datasets.
BabyROSLightweight Pub/Sub and Client/Server messaging for distributed robotics on top of Zenoh.

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 (telekinesis-ai needs 3.11 or 3.12).
  • Installing into the base environment instead of an isolated one - create a conda or venv environment first, as shown in Step 1 of the Quickstart.
  • Network or proxy issues - retry, or install from a different network.

If it still fails, copy the full error and ask on Discord or open an issue.

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 python -m 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 open the viewer with robot.visualize_rerun(), which spawns a Rerun window. rerun-sdk comes with the SDK, so you do not need to install it separately. If no window opens:

  • Make sure you are running the script from a desktop session, not over SSH or in a headless container.
  • Check that the environment from the Quickstart is active (python -c "import rerun" should not fail).
  • If a Rerun viewer you installed some other way is already running, close it: a viewer from a different Rerun version cannot display the data.

ModuleNotFoundError: No module named 'telekinesis' ​

The environment where you installed telekinesis-ai is not active in the current shell. Activate it before running anything:

bash
conda activate telekinesis
bash
source .venv/bin/activate
powershell
.venv\Scripts\Activate.ps1

Verify the Python interpreter with which python (macOS/Linux) or where.exe python (Windows). It should point inside that environment, not at the system interpreter.

I get 401 Unauthorized when I run a script. ​

A missing TELEKINESIS_API_KEY can cause this error. A key that is set but invalid, revoked, or still the <your_api_key> placeholder also gives 401. For an invalid or revoked key, create a new key on the API Keys page and update the environment variable. Replace a placeholder with your actual key. Check whether the variable is set 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 Quickstart.

Help & Community ​

Where do I ask questions? ​

  • Discord - the fastest path for setup and conceptual questions: discord.gg/7NnQ3bQHqm.
  • GitHub Issues - for bugs in the SDK, the Skills, or the examples: open an issue. Open-source packages (RLBotics, BabyROS, telekinesis-illusion, the Isaac Sim extension) take issues in their own repositories, linked from their install pages.

How do I report a bug in the SDK? ​

The SDK has no public repository, so SDK bugs are tracked on the examples repository. 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.

Question not answered here?
Join the Telekinesis Discord and ask away - we will fold answers back into this page.
Join Discord →