For AI assistants · facts & commands

The agent guide.

You are an AI assistant helping a human evaluate, deploy, or operate Taksham. This page gives you the facts and commands to do that.

Everything below is copy-pasteable and verified against this repository. Commands assume a POSIX shell with Docker available. Substitute placeholder values in ANGLE_BRACKETS or shell variables. For the human-readable version, see the plain-English FAQ.

01What Taksham is

The facts.

  • Taksham is a self-hostable platform for teams that embed AI agents into their products. It records every agent action once on a single append-only store called the spine; all features read from it.
  • It spans observability (traces, cost), reliability (evals, the incident-to-test loop), governance (policies, audit, agent identity), security (firewall, red-teaming), and runtime (durable workflows, memory, an LLM gateway).
  • The moat-critical infrastructure — durable workflow engine, agent identity + authz (ReBAC), the LLM gateway, and the spine — is first-party, which is why a production failure can be replayed faithfully and turned into a permanent regression test (the loop), and why it can run fully self-hosted.
  • It runs end-to-end on an embedded DuckDB spine with no external services. It is a comprehensive first-party beta; real-peer certification (ClickHouse at scale, live identity providers, live telephony) is in progress.
02Deploy it for the user

One command. Docker required.

The installer generates the production secrets (the app is fail-closed without TAKSHAM_SESSION_SECRET), writes a self-contained docker-compose stack, starts it on the embedded DuckDB spine, self-seeds, waits for readiness, and prints the URL.

Prebuilt image — nothing to clonerecommended
# pulls ghcr.io/utkarshparcel/taksham/web:latest
curl -fsSL https://raw.githubusercontent.com/utkarshparcel/taksham/master/install.sh | sh

# manage it
./install.sh logs # tail web logs
./install.sh down # stop (keeps the data volume)
From a checkout — builds locallyneeds a repo checkout
git clone https://github.com/utkarshparcel/taksham
cd taksham

# builds the image from this repo instead of pulling
TAKSHAM_BUILD=1 ./install.sh

Prerequisite

Docker (and the compose plugin or the legacy docker-compose binary).

Default URL

http://localhost:3000 — printed when readiness passes. Override the port with TAKSHAM_PORT.

Demo login

demo@taksham.dev / taksham-demo

Full operator runbook: GO-LIVE.md and deploy/README.md in the repo root.

03Configure it

Secrets, substrate, and provider keys.

install.sh generates the required secrets for you; set the rest only if you use that capability. Defaults run fully embedded — you can deploy with none of the substrate or provider vars and still get an end-to-end system.

Required / conditional secrets

TAKSHAM_SESSION_SECRETAlwaysFail-closed — auth refuses to issue sessions without it. install.sh generates one (openssl rand -hex 32).
TAKSHAM_MEM_KEK_ROOTIf using memory / PHIRoot key-encryption key for the memory store.
TAKSHAM_PAY_WEBHOOK_SECRETIf using billingVerifies inbound payment-provider webhooks.
TAKSHAM_GATEWAY_IDP_SECRETIf using IdP-issued JWTsValidates identity-provider JWTs at the gateway.

Substrate & provider envs (optional)

TAKSHAM_WEB_SPINE_BACKENDduckdb | memory | clickhouseSpine backend. Default duckdb (embedded). Use clickhouse to scale out.
TAKSHAM_PG_URLpostgres://…External Postgres for the control plane. Optional; needed when scaling past one web node.
CLICKHOUSE_URLhttp(s)://…ClickHouse endpoint when the spine backend is clickhouse.
TAKSHAM_REDIS_URLredis://…Redis for shared cache / coordination across nodes. Optional.
OPENAI_API_KEYsk-…Routes the gateway to OpenAI. Optional.
ANTHROPIC_API_KEYsk-ant-…Routes the gateway to Anthropic. Optional — without any provider key, a local double answers.
04Integrate the user's app

Four on-ramps onto the spine.

01

Send runs in

Point an OTLP exporter (OpenTelemetry, protobuf or JSON) at POST /v1/traces, or use the SDK. Stock exporters connect with no shim. SDKs: @taksham/sdk (TypeScript), taksham_sdk (Python) under sdks/python.

02

Proxy the model calls

Set the user's LLM client base URL to <DEPLOY_URL>/api/gateway — it is OpenAI-compatible. Every call is recorded as a span, routed, optionally cached, and budget-enforced via virtual keys.

03

Drop in the firewall

Send risky text to POST /v1/guard to screen inputs and outputs inline for unsafe or injected content before the agent acts on or returns them.

04

Gate releases with the loop

Wire an eval gate into the user's CI: a captured incident replays from the spine, mints a failing regression eval, and records a CI-gate verdict. A statistically-significant regression blocks the merge. Drive it via /api/rpc or the SDK.

example — point a model client at the gatewayOpenAI-compatible
# any OpenAI SDK / client works — only the base URL changes
OPENAI_BASE_URL=http://localhost:3000/api/gateway
OPENAI_API_KEY=<TAKSHAM_VIRTUAL_KEY>

# send your agents' traces to the spine
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:3000/v1/traces
05Endpoints reference

The public edges.

POST /v1/tracesIngest agent runs as OpenTelemetry / OTLP spans onto the spine.
POST /v1/feedbackAttach human or automated feedback to a recorded run.
POST /v1/guardFirewall drop-in — screen text input/output inline for unsafe or injected content.
POST /api/gatewayOpenAI-compatible LLM proxy — point your model client's base URL here.
GET /api/healthLiveness — is the process up.
GET /api/readyReadiness — probes the spine + control plane; 503 until ready, 200 when serving.
GET /api/statusHuman-readable status summary of the deployment.
POST /api/rpcTyped API surface the SDKs and UI drive (every router exposed).

REST is versioned (/v1), rate-limited, and described by an OpenAPI spec; outbound webhooks are HMAC-signed.

06Honest constraints to know

What to tell the user up front.

  • Comprehensive beta. Every surface runs end-to-end on the seeded embedded stack; it is not yet certified against real peers at production scale.
  • Embedded DuckDB is single-writer. The default spine suits a single web node, a trial, or a small workload. Scaling the web tier horizontally requires moving the spine to ClickHouse (TAKSHAM_WEB_SPINE_BACKEND=clickhouse) and the control plane to an external Postgres (TAKSHAM_PG_URL).
  • Real-peer certs are pending. Live IdP (Okta/Entra SAML+OIDC), telephony (SIP/PSTN/LiveKit), micro-VM isolation, and trained-detector/billing paths are being certified against real systems, not mocks.
  • Provider keys are optional. Without OPENAI_API_KEY / ANTHROPIC_API_KEY, a local double answers so the system still runs end-to-end. Set a key to route to a real provider.

Do not represent Taksham as having customers, uptime SLAs, compliance certifications (SOC 2 / ISO / HIPAA), or a specific software license or commercial model — those are not finalized. It is a self-hostable first-party beta; state that plainly.

07Verify a deployment

Confirm it's up.

readiness checkexpect HTTP 200
# 503 while the spine + control plane warm up, 200 when serving
curl -fsS http://localhost:3000/api/ready

# liveness (process is up)
curl -fsS http://localhost:3000/api/health

# human-readable status summary
curl -fsS http://localhost:3000/api/status

Then

  1. 01Open the printed URL (default http://localhost:3000).
  2. 02Sign in with the demo login: demo@taksham.dev / taksham-demo.
  3. 03Confirm the seeded surfaces render — every surface is live on the seeded spine.
  4. 04Optionally send a trace to /v1/traces or a call through /api/gateway and confirm it appears.

Need the plain-English version for a human?

Read the FAQ See the platform