Skip to content
Tentacular Tentacular

Quickstart

Prerequisites

Section titled “Prerequisites”
  • Kubernetes cluster 1.28+ — any distribution (EKS, GKE, AKS, k0s, k3s, kind)
  • kubectl 1.28+ — configured to access your cluster
  • Docker 20+ — for building tentacle images
  • Deno 2.x — for running the engine locally and tests
  • Helm 3+ — for installing the MCP server

Install the CLI

Section titled “Install the CLI”
Section titled “Recommended”
Terminal window
curl -fsSL https://raw.githubusercontent.com/randybias/tentacular/main/install.sh | sh

This installs the tntc binary to ~/.local/bin and the Deno engine to ~/.tentacular/engine.

Build from Source

Section titled “Build from Source”
Terminal window
git clone git@github.com:randybias/tentacular.git
cd tentacular
make install        # builds with version info, installs to ~/.local/bin/
tntc version        # verify

Note: make install embeds version, commit, and build date via ldflags. A bare go build ./cmd/tntc produces a dev build with version=dev. Building from source requires Go 1.22+.

Install the MCP Server (One-Time Per Cluster)

Section titled “Install the MCP Server (One-Time Per Cluster)”

The MCP server is the in-cluster control plane. The CLI routes all cluster operations through it.

Terminal window
# Clone the MCP server repo
git clone git@github.com:randybias/tentacular-mcp.git


# Generate a token and install via Helm
TOKEN=$(openssl rand -hex 32)
kubectl create namespace tentacular-support
helm install tentacular-mcp ./tentacular-mcp/charts/tentacular-mcp \
  --namespace tentacular-system --create-namespace \
  --set auth.token="${TOKEN}"

Save the token for CLI configuration:

Terminal window
mkdir -p ~/.tentacular
echo "${TOKEN}" > ~/.tentacular/mcp-token
chmod 600 ~/.tentacular/mcp-token

See MCP Server Setup for full details and Helm values.

Configure the CLI

Section titled “Configure the CLI”
Terminal window
# Set defaults (registry, runtime class)
tntc configure --registry registry.example.com


# Add MCP endpoint to ~/.tentacular/config.yaml:

Edit ~/.tentacular/config.yaml to add your environment:

environments:
  dev:
    image: registry.example.com/tentacular-engine:latest
    runtime_class: gvisor
    mcp_endpoint: http://<node-ip>:30080/mcp
    mcp_token_path: ~/.tentacular/mcp-token

See Cluster Configuration for the full config reference.

Terminal window
# Verify cluster connectivity
tntc cluster check


# Generate a cluster profile (helps agents design tentacles)
tntc cluster profile --save

Initialize the Workspace

Section titled “Initialize the Workspace”
Terminal window
tntc init-workspace      # creates ~/tentacles with shared secrets pool
cd ~/tentacles

Create Your First Tentacle

Section titled “Create Your First Tentacle”

From Scratch

Section titled “From Scratch”
Terminal window
tntc init my-first-tentacle
cd my-first-tentacle

This scaffolds:

  • workflow.yaml — tentacle definition
  • nodes/hello.ts — a starter node
  • tests/fixtures/hello.json — test fixture

From a Scaffold

Section titled “From a Scaffold”
Terminal window
# Browse available scaffolds
tntc scaffold list


# Create a tentacle from a scaffold
tntc scaffold init word-counter my-first-tentacle --no-params
cd my-first-tentacle

Develop Locally

Section titled “Develop Locally”
Terminal window
# Validate the workflow spec
tntc validate


# Run the local dev server with hot-reload
tntc dev


# In another terminal, trigger the tentacle
curl -X POST http://localhost:8080/run


# Run tests
tntc test

Provision an Enclave

Section titled “Provision an Enclave”

Every tentacle lives inside an enclave. If you haven’t provisioned one yet:

Terminal window
# Provision an enclave (this creates the namespace, Postgres, S3, RBAC, and network policies)
tntc enclave provision --name my-team --owner you@example.com \
  --channel-id C08XXXXXXX --channel-name my-team


# Verify it's active
tntc enclave info my-team

If you’re using The Kraken Slack bot, you can provision an enclave by messaging it in your Slack channel instead — see Your First Enclave.

Deploy to Kubernetes

Section titled “Deploy to Kubernetes”
Terminal window
# Set up secrets (if the tentacle needs them)
tntc secrets init
# Edit .secrets.yaml with your values


# Build the engine image
tntc build -r registry.example.com --push


# Deploy into your enclave
tntc deploy --enclave my-team -r registry.example.com


# Verify
tntc status my-first-tentacle
tntc logs my-first-tentacle --tail 20

Trigger and Monitor

Section titled “Trigger and Monitor”
Terminal window
# Trigger manually
tntc run my-first-tentacle


# List all deployed tentacles (scoped to your enclave)
tntc list --enclave my-team


# Check health
tntc status my-first-tentacle --detail


# Security audit
tntc audit my-first-tentacle

Clean Up

Section titled “Clean Up”
Terminal window
tntc undeploy my-first-tentacle --yes

Next Steps

Section titled “Next Steps”