Installation
The guide below walks you through installing the Telekinesis Agentic Skill Library, setting up your API key, and preparing a clean Python environment for your first Telekinesis project.
By the end of this guide, you will have:
- Created a Telekinesis API key
- Configured the
TELEKINESIS_API_KEYenvironment variable - Created an isolated Python environment
- Installed the
telekinesis-aiSDK - Verified that the SDK is working
Prerequisites
Before you begin, make sure you have:
- Python 3.11 or 3.12 — required for the
telekinesis-aiSDK - A package manager — we recommend Miniconda for isolated environments
Supported Python versions
We currently support Python 3.11 and 3.12 only. Make sure your environment uses one of these versions before installing the SDK.
Step 1: Create an API Key
Your Telekinesis API key authenticates every request the SDK makes to the Telekinesis platform. Follow the steps below to create an account and generate your first key.
1. Create your Telekinesis account
Sign up — or log in if you already have an account — at the Telekinesis platform:
Go to platform.telekinesis.ai →
You can sign up with email and password. After signing up with email, check your inbox for a verification link and confirm your address before continuing. Sometimes, it could also be in your spam folder.
FREE TIER PLAN
Every new Telekinesis account comes with a free tier that includes credits to call the SDK and run skills. You do not have to provide any billing details currently.
2. Generate an API key
Once you are logged in, open the API Keys page and click Create new key. Give the key a descriptive name (for example, local-testing, or telekinesis-key) so you can recognise it later when you have several keys.
The video below walks through the full sign-up and API key creation flow, done for Mac:
Creating a Telekinesis account and generating your first API key.
3. Copy and store the key
Copy the key and store it somewhere safe, such as:
- A password manager (1Password, Bitwarden, etc.)
- Your shell configuration file (e.g.
.zshrc,.bashrc) - Your team's secrets manager (AWS Secrets Manager, GitHub Actions secrets, etc)
Once a key is deleted or revoked, you cannot use it again. You have to create a new one.
COPY KEY
For security, the full API key is shown only once, right after it is created. If you close the dialog without copying it, you will need to delete the key and generate a new one.
In the next step you will load this key into your environment as TELEKINESIS_API_KEY.
4. Manage your keys safely
A few best practices to keep your account and projects secure:
- Never commit keys to source control. Always load them from environment variables or a secrets manager — never hard-code them in Python files, notebooks, or
.envfiles that are committed to git. - Rotate keys regularly. Generate a new key, update your environments, then delete the old one from the API Keys page.
- Revoke compromised keys immediately. If a key is leaked or you lose track of where it is used, delete it from the platform — any client still using it will start failing authentication right away.
Step 2: Configure the API Key
Export the API key as an environment variable so the Telekinesis SDK can authenticate your requests automatically. In every command below, replace <your_api_key> with the key generated in Step 1.
Windows (PowerShell)
Persist the key for all future PowerShell sessions:
setx TELEKINESIS_API_KEY "<your_api_key>"Also set it in the current shell session so you can use it immediately without restarting the terminal:
$env:TELEKINESIS_API_KEY="<your_api_key>"Verify the key is set:
echo $env:TELEKINESIS_API_KEYYou should see the value of the key printed in the terminal.
INFO
setx updates future PowerShell sessions. Once you open a new terminal, the key will already be available.
macOS / Linux
First, determine your shell type:
echo $SHELLThen, depending on your shell, run the appropriate command to persist the API key:
# bash
echo 'export TELEKINESIS_API_KEY="<your_api_key>"' >> ~/.bashrc && source ~/.bashrc# zsh
echo 'export TELEKINESIS_API_KEY="<your_api_key>"' >> ~/.zshrc && source ~/.zshrc# fish
echo 'set -gx TELEKINESIS_API_KEY "<your_api_key>"' >> ~/.config/fish/config.fish && source ~/.config/fish/config.fishVerify the key is set:
echo $TELEKINESIS_API_KEYYou should see the value of the key printed in the terminal.
NOTE
The Telekinesis SDK reads TELEKINESIS_API_KEY directly from your environment, so no further configuration is needed in your Python code.
Step 3: Create a Python Environment
Create an isolated environment to avoid dependency conflicts. We recommend using conda:
1. Create a new environment called telekinesis:
conda create -n telekinesis python=3.112. Activate the environment:
conda activate telekinesisStep 4: Install the Telekinesis SDK
With the environment active, install the core SDK using pip:
pip install telekinesis-aitelekinesis-datatypes is installed automatically with telekinesis-ai. Provides canonical, strongly-typed 2D and 3D structures — images, point clouds, meshes — that act as the data contract shared by every Telekinesis skill and agent.Step 5: Verify the Installation
Confirm the SDK is installed correctly by importing it from a Python shell:
python -c "import telekinesis; from telekinesis import cornea, retina, pupil, vitreous"There should be no error.
Module-Specific Installation
The telekinesis-ai SDK is modular. The above installs all the vision related modules of Telekinesis Agentic Skill Library. There are other modules, each module with its own installation instructions for dependencies or hardware drivers it needs.
Pick the modules you plan to use and follow their dedicated guides.
pip install telekinesis-ai[synapse]pip install telekinesis-ai[medulla]VS Code Marketplace: search "Tzara"Next Steps
Once the SDK is installed and verified, head to the Quickstart to run your first Telekinesis skill end-to-end.