Getting Started

Overview

You'll install Tansive in just a few minutes
Run two quick demos
- Policy-Driven Agent: Watch how Tansive controls agent and tool invocations in real time with fine-grained policies. Instantly see which actions are allowed or denied, and why.
- Secure Data Handling: Learn how Tansive protects sensitive information using pinned session variables working alongside a user-defined transform.

Next Steps:

Dive deeper into how these demos work under the hood to understand concepts and architecture.
Start building your own secure, auditable workflows.
Explore ways to get help, share feedback, and contribute. Tansive is fully open-source.

Installation

Prerequisites

Latest stable version of Docker desktop or Docker Engine 🔗
Git
Platform Support :
- macOS (Apple Silicon) and Linux (x86_64 and ARM64) are fully supported and tested.
- On Windows 11, the Tansive CLI client is supported natively. Tansive Server and Runtime are supported under WSL2
An OpenAI or Anthropic API Key is required to run the demos.
- The demo script uses the OpenAI Python SDK.
- Each run consumes approximately 10,000 input tokens and 1000 output tokens.
No API Key? No Problem. Sample real output is provided, so you can follow along without running the demo.

Installation

🕒 Total time: 5-7 minutes

1. Clone the Tansive installation repository:

git clone [email protected]:tansive/tansive-quickstart

cd tansive-quickstart

2. Start Tansive

Tansive Server uses PostgreSQL to store the catalog.
We provide a one-line setup that brings up:

PostgreSQL
Tansive Server
The Tansive Runtime Agent(called Tangent)

docker compose -f docker-compose-aio.yaml up -d

Wait for the tangent container to start before proceeding.

3. Install the Tansive CLI

Choose your platform below for installation instructions:

Linux

Download and install the Tansive CLI for Linux:

For x86_64/amd64 systems:

# Download the latest release
curl -LO https://github.com/tansive/tansive/releases/download/v0.1.0-alpha.2/tansive-0.1.0-alpha.2-linux-amd64

# Make the binary executable
chmod +x tansive-0.1.0-alpha.2-linux-amd64

# Move the binary to a directory in your PATH
sudo install -m 0755 tansive-0.1.0-alpha.2-linux-amd64 /usr/local/bin/tansive

# Clean up
rm tansive-0.1.0-alpha.2-linux-amd64

# Verify installation
tansive version

For arm64 systems:

# Download the latest release
curl -LO https://github.com/tansive/tansive/releases/download/v0.1.0-alpha.2/tansive-0.1.0-alpha.2-linux-arm64

# Make the binary executable
chmod +x tansive-0.1.0-alpha.2-linux-arm64

# Move the binary to a directory in your PATH
sudo install -m 0755 tansive-0.1.0-alpha.2-linux-arm64 /usr/local/bin/tansive

# Clean up
rm tansive-0.1.0-alpha.2-linux-arm64

# Verify installation
tansive version

macOS

Download and install the Tansive CLI for macOS:

For x86_64 / Intel Macs:

# Download the latest release
curl -LO https://github.com/tansive/tansive/releases/download/v0.1.0-alpha.2/tansive-0.1.0-alpha.2-darwin-amd64

# Make the binary executable
chmod +x tansive-0.1.0-alpha.2-darwin-amd64

# Move the binary to a directory in your PATH
sudo install -m 0755 tansive-0.1.0-alpha.2-darwin-amd64 /usr/local/bin/tansive

# Clean up
rm tansive-0.1.0-alpha.2-darwin-amd64

# Verify installation
tansive version

For Apple Silicon (M1/M2/M3) Macs:

# Download the latest release
curl -LO https://github.com/tansive/tansive/releases/download/v0.1.0-alpha.2/tansive-0.1.0-alpha.2-darwin-arm64

# Make the binary executable
chmod +x tansive-0.1.0-alpha.2-darwin-arm64

# Move the binary to a directory in your PATH
sudo install -m 0755 tansive-0.1.0-alpha.2-darwin-arm64 /usr/local/bin/tansive

# Clean up
rm tansive-0.1.0-alpha.2-darwin-arm64

# Verify installation
tansive version

Windows

Download and install the Tansive CLI for Windows:

Using Browser:

Download Tansive command line CLI.
Move the downloaded file to a directory in your PATH (e.g., C:\Users\YourUsername\bin\)
Add the directory to your system PATH:
- Right-click on "This PC" or "My Computer" → Properties → Advanced system settings → Environment Variables
- Under "User variables", find "Path" and click "Edit"
- Click "New" and add the full path to the directory (e.g., C:\Users\YourUsername\bin)
- Click "OK" on all dialogs
Restart your command prompt or PowerShell
Verify installation: tansive version

Using PowerShell:

# Create bin directory if needed
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\bin"

# Download the binary
$binaryPath = "$env:USERPROFILE\bin\tansive.exe"
Invoke-WebRequest -Uri "https://github.com/tansive/tansive/releases/download/v0.1.0-alpha.2/tansive-0.1.0-alpha.2-windows-amd64.exe" -OutFile $binaryPath

# Update PATH for current session
$env:PATH += ";$env:USERPROFILE\bin"

# Update PATH permanently if not already set
$currentPath = [Environment]::GetEnvironmentVariable("PATH", "User")
if ($currentPath -notlike "*$env:USERPROFILE\bin*") {
    [Environment]::SetEnvironmentVariable("PATH", "$currentPath;$env:USERPROFILE\bin", "User")
}

# Verify installation
tansive version

Tip: You may need to restart your terminal to pick up the updated PATH

4. Configure the CLI

After installation, you'll need to configure the CLI to connect to your Tansive server.
In this version Tansive server operates in single user mode. So you can login directly.

# Set the server URL (default exposed by the docker install)
tansive config --server https://local.tansive.dev:8678

# Login
tansive login

# Verify Status
tansive status

Setup a Catalog

🕒 Total time: 2 minutes

1. Configure API Keys

Create a .env file in the project root with your OpenAI or Anthropic API Key. Replace only the API keys you want to use - keep the placeholder for keys you don't need (e.g., if you only use Claude, keep "<your-openai-key-here>" as-is).

# Create the .env file
# Replace only the API keys you want to use - keep placeholders for unused keys
cat > .env << 'EOF'
CLAUDE_API_KEY="<your-claude-key-here>"
OPENAI_API_KEY="<your-openai-key-here>"
# don't modify this. you don't need a kubernetes cluster!
KUBECONFIG="YXBpVmVyc2lvbjogdjEKa2luZDogQ29uZmlnCmNsdXN0ZXJzOgogIC0gbmFtZTogbXktY2x1c3RlcgogICAgY2x1c3RlcjoKICAgICAgc2VydmVyOiBodHRwczovL2Rldi1lbnYuZXhhbXBsZS5jb20KICAgICAgY2VydGlmaWNhdG9yaXR5LWRhdGE6IDxiYXNlNjQtZW5jb2RlZC1jYS1jZXJ0Pg=="
EOF

2. Setup a Catalog via declarative scripts

# sets up a new catalog with dev and prod variants, and SkillSets
bash examples/catalog_setup/setup.sh

# view the catalog structure that was setup
tansive tree

Run the demos

Run the Policy-driven agent

🕒 Total time: 3 minutes

In this demo, you'll simulate an agent solving a Kubernetes incident. You'll create a catalog, define tools and policies, and watch how Tansive enforces them differently across environments - without needing a real cluster.

Scenario

This is a fictional debugging scenario involving an e-commerce application deployed on Kubernetes. The application is unable to take orders, and you'll use an AI Agent to investigate the issue.

Two tools are available to the agent:

list-pods - lists the status of running pods using a label selector.

restart-deployment - restarts a deployment by name.

Both tools are shell scripts that return mock output formatted like kubectl, so you can run the demo without needing a real Kubernetes cluster. The tools are implemented in skillset_scripts/tools_script.sh

The purpose of this demo is to show how Tansive enforces policy at runtime. Specifically, we'll block the use of restart-deployment in the production environment, but allow it in dev environment.

Run the Skill

Start a session in the dev environment using the k8s_troubleshooter skill:

If you provided a CLAUDE-API-KEY, change the "model" value to "claude"

tansive session create /demo-skillsets/kubernetes-demo/k8s_troubleshooter \
--view dev-view \
--input-args '{"prompt":"An order-placement issue is affecting our e-commerce system. Use the provided tools to identify the root cause and take any necessary steps to resolve it.","model":"gpt4o"}'

You should see an output similar to the following:

Dev View: Click to expand sample output

venv-test ❯ tansive session create /demo-skillsets/kubernetes-demo/k8s_troubleshooter \
--view dev-view \
--input-args '{"prompt":"An order-placement issue is affecting our e-commerce system. Use the provided tools to identify the root cause and take any necessary steps to resolve it.","model":"gpt4o"}'

Session ID: 0197a905-8eba-7294-8822-130d2fbb940c
    Start: 2025-06-25 14:36:43.215 PDT

  [00:00.000] [tansive] ▶ requested skill: k8s_troubleshooter
  [00:00.003] [tansive] 🛡️ allowed by Tansive policy: view 'dev-view' authorizes actions - [kubernetes.troubleshoot] - to use this skill
  [00:00.004] [system.stdiorunner] ▶ running skill: k8s_troubleshooter
  [00:01.256] k8s_troubleshooter ▶ 🤔 Thinking: None
  [00:01.259]  ▶ requested skill: list_pods
  [00:01.259]  🛡️ allowed by Tansive policy: view 'dev-view' authorizes actions - [kubernetes.pods.list] - to use this skill
  [00:01.260] [system.stdiorunner] ▶ running skill: list_pods
  [00:01.274] list_pods ▶ NAME                                READY   STATUS    RESTARTS   AGE
                                   api-server-5f5b7f77b7-zx9qs          1/1     Running   0          2d
                                   web-frontend-6f6f9d7b7b-xv2mn        1/1     Running   1          5h
                                   cache-worker-7d7d9d9b7b-pv9lk        1/1     Running   0          1d
                                   orders-api-7ff9d44db7-abcde          0/1     CrashLoopBackOff   12         3h
  [00:01.274] list_pods ▶ # Filter applied: app=ecommerce
  [00:01.274] [system.stdiorunner] ▶ skill completed successfully: list_pods
  [00:06.724] k8s_troubleshooter ▶ 🤔 Thinking: The issue seems to be with the `orders-api` pod, which is in a `CrashLoopBackOff` state. This indicates that the pod is failing to start properly and is repeatedly crashing.

                                   To address this, I will attempt to restart the `orders-api` deployment to see if that resolves the issue.
  [00:06.725]  ▶ requested skill: restart_deployment
  [00:06.725]  🛡️ allowed by Tansive policy: view 'dev-view' authorizes actions - [kubernetes.deployments.restart] - to use this skill
  [00:06.727] [system.stdiorunner] ▶ running skill: restart_deployment
  [00:06.747] restart_deployment ▶ deployment.apps/orders-api restarted
  [00:06.747] [system.stdiorunner] ▶ skill completed successfully: restart_deployment
  [00:09.490] k8s_troubleshooter ▶ ✅ Final response: I have restarted the `orders-api` deployment. Please monitor the pod to ensure it transitions to a stable state. If the issue persists, further investigation may be needed to identify underlying problems, such as configuration errors or code issues.
  [00:09.553] [system.stdiorunner] ▶ skill completed successfully: k8s_troubleshooter

In this interactive agent session, the k8s_troubleshooter used the list_pods skill to obtain the status of running pods, determined that the orders-api pod was is a CrashLoopBackOff state, and used the restart_deployment skill in an attempt to fix the problem. If you had used claude you may see multiple invocations of the restart_deployment skill in an attempt to verify if the restart actually fixed the problem. Claude is thorough!

Now we will do the same but switch the session to production view. We will only change the view name in the --view option.

tansive session create /demo-skillsets/kubernetes-demo/k8s_troubleshooter \
--view prod-view \
--input-args '{"prompt":"An order-placement issue is affecting our e-commerce system. Use the provided tools to identify the root cause and take any necessary steps to resolve it.","model":"gpt4o"}'

You should see an output similar to the following:

Prod View: Click to expand sample output

venv-test ❯ tansive session create /demo-skillsets/kubernetes-demo/k8s_troubleshooter \
--view prod-view \
--input-args '{"prompt":"An order-placement issue is affecting our e-commerce system. Use the provided tools to identify the root cause and take any necessary steps to resolve it.","model":"gpt4o"}'

Session ID: 0197a91d-451d-75a4-894a-f126f909689f
    Start: 2025-06-25 15:02:37.235 PDT

  [00:00.000] [tansive] ▶ requested skill: k8s_troubleshooter
  [00:00.004] [tansive] 🛡️ allowed by Tansive policy: view 'prod-view' authorizes actions - [kubernetes.troubleshoot] - to use this skill
  [00:00.005] [system.stdiorunner] ▶ running skill: k8s_troubleshooter
  [00:01.438] k8s_troubleshooter ▶ 🤔 Thinking: None
  [00:01.440]  ▶ requested skill: list_pods
  [00:01.441]  🛡️ allowed by Tansive policy: view 'prod-view' authorizes actions - [kubernetes.pods.list] - to use this skill
  [00:01.442] [system.stdiorunner] ▶ running skill: list_pods
  [00:01.460] list_pods ▶ NAME                                READY   STATUS    RESTARTS   AGE
                                   api-server-5f5b7f77b7-zx9qs          1/1     Running   0          2d
                                   web-frontend-6f6f9d7b7b-xv2mn        1/1     Running   1          5h
                                   cache-worker-7d7d9d9b7b-pv9lk        1/1     Running   0          1d
                                   orders-api-7ff9d44db7-abcde          0/1     CrashLoopBackOff   12         3h
                                   # Filter applied: app=e-commerce
  [00:01.460] [system.stdiorunner] ▶ skill completed successfully: list_pods
  [00:04.142] k8s_troubleshooter ▶ 🤔 Thinking: The `orders-api` pod is in a `CrashLoopBackOff` state, which likely indicates the issue with the order-placement in your e-commerce system. I'll attempt to restart the `orders-api` deployment to see if that resolves the problem.
  [00:04.143]  ▶ requested skill: restart_deployment
  [00:04.143]  🛡️ blocked by Tansive policy: view 'prod-view' does not authorize any of required actions - [kubernetes.deployments.restart] - to use this skill
  [00:07.646] k8s_troubleshooter ▶ ✅ Final response: I tried to use Skill: functions.restart_deployment for restarting the `orders-api` deployment to resolve the order-placement issue, but it was blocked by Tansive policy. Please contact the administrator of your Tansive system to obtain access.
  [00:07.724] [system.stdiorunner] ▶ skill completed successfully: k8s_troubleshooter

When we switched the view to production, Tansive blocked the invocation of the restart_deployment skill based on the policy bound to the prod-view. If you saw similar output - 🎉 Congratulations! You have successfully setup Tansive and executed your first policy-enforced agentic workflow.

Now that you've run your first policy-bound agent, try modifying the policy file to block list_pods instead — or switch between the claude and gpt4o model and observe how they differ in their retry behavior. To experiment, open catalog_config/catalog-setup.yaml and inspect the YAML documents with kind: View. Compare the rules for target: kubernetes-demo in dev-view versus prod-view — that's where the policy enforcement is defined. After making changes, apply the updated configuration with:

tansive apply -f catalog_config/catalog-setup.yaml

Run the Secure Data Handling demo

🕒 Total time: 3 minutes

In this hands-on demo, you'll simulate a health bot that answers medical questions while enforcing strict access controls. You'll see how Tansive can protect Personal Health Information (PHI) in real time.

Scenario

This is a fictional debugging scenario involving a health bot that answers questions about an authenticated caller's health.

Two tools are available to the agent:

resolve-patient-id - provides the ID of a patient (patient_id), given their name. This tool is written in Javascript skillset_scripts/resolve-patient-id.js

patient-bloodwork - returns patient's blood test results, given their patient_id. This tool is written in Python skillset_scripts/patient_bloodwork.py

The purpose of this demo is to show how Tansive can be used to validate and filter inputs to enforce data boundaries. Specifically, you'll pin the session to John's patient_id so that any attempt to access records for other patients, like Sheila, will be blocked automatically.

Run the Skill

Start a session in the dev environment using the skillset-patient skill:

If you provided a OPENAI-API-KEY, change the "model" value to "gpt4o"

tansive session create /demo-skillsets/health-record-demo/health-record-agent \
--view dev-view \
--input-args '{"prompt":"I think John  might be having an infection. Can you please check?","model":"claude"}' \
--session-vars '{"patient_id":"H12345"}'

In the command, we added a new parameter called session-vars that allows us to define session specific variables. We set the patient_id to John's id. You should see an output similar to the following:

Successful result for John: Click to expand sample output

myenv ❯ tansive session create /demo-skillsets/health-record-demo/health-record-agent \
--view dev-view \
--input-args '{"prompt":"I think John  might be having an infection. Can you please check?","model":"claude"}' \
--session-vars '{"patient_id":"H12345"}'

Session ID: 0197ba7a-274e-7603-ac6b-32763515b010
Start: 2025-06-28 23:57:37.129 PDT

[00:00.000] [tansive] ▶ requested skill: health-record-agent
[00:00.003] [tansive] 🛡️ allowed by Tansive policy: view 'dev-view' authorizes actions - [patient.labresults.get] - to use this skill
[00:00.004] [system.stdiorunner] ▶ running skill: health-record-agent
[00:03.672] health-record-agent ▶ 🤔 Thinking: I'd be happy to check John's bloodwork for any signs of infection. To do this, I'll need to retrieve John's medical records.

                                   First, let me resolve John's patient ID, then I'll look up his bloodwork results.

[00:03.675] ▶ requested skill: resolve-patient-id
[00:03.675] 🛡️ allowed by Tansive policy: view 'dev-view' authorizes actions - [patient.id.resolve] - to use this skill
[00:03.677] [system.stdiorunner] ▶ running skill: resolve-patient-id
[00:03.723] resolve-patient-id ▶ {
"patient_id": "H12345"
}
[00:03.726] [system.stdiorunner] ▶ skill completed successfully: resolve-patient-id
[00:05.456] health-record-agent ▶ 🤔 Thinking: Now I'll check John's bloodwork with the patient ID:
[00:05.457] ▶ requested skill: patient-bloodwork
[00:05.457] 🛡️ allowed by Tansive policy: view 'dev-view' authorizes actions - [patient.labresults.get] - to use this skill
[00:05.460] [system.stdiorunner] ▶ running skill: patient-bloodwork
[00:05.502] patient-bloodwork ▶ {"patient_id": "H12345", "bloodwork": {"hemoglobin": 13.5, "white_cell_count": 6.2, "platelets": 250, "glucose": 98, "cholesterol": {"total": 180, "ldl": 100, "hdl": 55}}}
[00:05.505] [system.stdiorunner] ▶ skill completed successfully: patient-bloodwork
[00:10.113] health-record-agent ▶ ✅ Final response: Based on John's bloodwork results, there doesn't appear to be clear evidence of an infection. Here's what I found:

                                   - White blood cell count: 6.2, which is within the normal range (typically 4.5-11.0). An elevated white blood cell count would be common during an infection.
                                   - Other values like hemoglobin (13.5) and platelets (250) are also within normal ranges.

                                   While John's bloodwork doesn't show obvious signs of infection, it's important to note that:
                                   1. Some infections might not cause changes in these basic blood parameters
                                   2. This is just one set of bloodwork and doesn't include other infection markers like C-reactive protein or procalcitonin
                                   3. Clinical symptoms and other diagnostic tests would be important to consider alongside these results

                                   If you're concerned about specific symptoms John is experiencing, it would be beneficial to discuss those with his healthcare provider for a complete evaluation.

[00:10.190] [system.stdiorunner] ▶ skill completed successfully: health-record-agent

After verifying the successful retrieval of John's bloodwork, you'll test what happens when the bot tries to access another patient's records:

tansive session create /demo-skillsets/health-record-demo/health-record-agent \
--view dev-view \
--input-args '{"prompt":"Sheila was looking sick. Can you please check her bloodwork?","model":"claude"}' \
--session-vars '{"patient_id":"H12345"}'

This time, Tansive will block the request, demonstrating how session-pinned variables can act as guardrails to prevent unauthorized access, even if the skill is otherwise allowed by policy.

You should see an output similar to the following:

Access blocked for Sheila's records: Click to expand sample output

myenv ❯ tansive session create /demo-skillsets/health-record-demo/health-record-agent \
--view dev-view  \
--input-args '{"prompt":"Sheila was looking sick. Can you please check her bloodwork?","model":"gpt4o"}' \
--session-vars '{"patient_id":"H12345"}'

Session ID: 0197ba82-2286-700f-b089-fa332ecc9554
    Start: 2025-06-29 00:06:20.186 PDT

  [00:00.000] [tansive] ▶ requested skill: health-record-agent
  [00:00.003] [tansive] 🛡️ allowed by Tansive policy: view 'dev-view' authorizes actions - [patient.labresults.get] - to use this skill
  [00:00.004] [system.stdiorunner] ▶ running skill: health-record-agent
  [00:01.413] health-record-agent ▶ 🤔 Thinking: None
  [00:01.416]  ▶ requested skill: resolve-patient-id
  [00:01.416]  🛡️ allowed by Tansive policy: view 'dev-view' authorizes actions - [patient.id.resolve] - to use this skill
  [00:01.417] [system.stdiorunner] ▶ running skill: resolve-patient-id
  [00:01.460] resolve-patient-id ▶ {
                                     "patient_id": "H23456"
                                   }
  [00:01.462] [system.stdiorunner] ▶ skill completed successfully: resolve-patient-id
  [00:02.128] health-record-agent ▶ 🤔 Thinking: None
  [00:02.129]  ▶ requested skill: patient-bloodwork
  [00:02.129]  🛡️ allowed by Tansive policy: view 'dev-view' authorizes actions - [patient.labresults.get] - to use this skill
  [00:02.130]  ❗ unable to transform input
                                    Error: Unauthorized to access patient bloodwork for patient H23456
  [00:02.799] health-record-agent ▶ ✅ Final response: I tried to use Skill: functions.patient-bloodwork for retrieving Sheila's bloodwork but it was blocked by Tansive policy. Please contact the administrator of your Tansive system to obtain access.
  [00:02.875] [system.stdiorunner] ▶ skill completed successfully: health-record-agent

Even though the policy permitted the skill, the session variable patient_id locked the session to John. This ensured that attempts to access Sheila's data were rejected.

Explore the Audit Log

Now you’ll retrieve the audit logs for your demo runs.

Audit logs are different from debug logs, which are typically printed to the console or sent to external systems for indexing and search. An audit log is an immutable, tamper-evident record of the steps and events that occurred during a session. Tansive logs audit events separately from debug logs. You can learn more about the structure and verification of audit logs in the Concepts section.

Get the list of sessions:

tansive session list

Copy the SESSION ID and paste it into the placeholder below:

tansive session audit-log get your-session-id-here -o friendly_name.tlog

Verify and open the log:

# Verify the log's integrity
tansive session audit-log verify friendly_name.tlog

# Generate and open a user-friendly HTML view
tansive session audit-log view friendly_name.tlog

The verify command validates the hash chain to confirm the log has not been tampered with. The view command generates an HTML version of the log. You can pass --no-open to view if you prefer to create the HTML file without automatically launching your browser.

View sample audit log generated from the Kubernetes demo. This log was produced using Claude, which called list-pods multiple times to confirm that the deployment restarted successfully. Skill invocations are sorted by timestamp and nested to show which calls invoked others.

Next Steps

Next, we'll dig in to the demos to see how they work under the hood.

Overview​

Installation​

Prerequisites​

Installation​

Setup a Catalog​

Run the demos​

Run the Policy-driven agent​

Run the Secure Data Handling demo​

Explore the Audit Log​

Next Steps​

Overview

Installation

Prerequisites

Installation

Setup a Catalog

Run the demos

Run the Policy-driven agent

Run the Secure Data Handling demo

Explore the Audit Log

Next Steps