7 min read Updated July 16, 2026

Quick Start Guide

Get Tamandua Sentinel running in under 5 minutes. This guide covers:

  1. Creating an account or starting self-hosted
  2. Deploying your first agent
  3. Viewing your first alert
  4. Verifying your on-chain proof

Prerequisites

Before you begin, ensure you have:

  • Docker and Docker Compose installed
  • A modern web browser
  • One endpoint to protect (Windows or Linux recommended; macOS is Preview/Experimental)

For detailed requirements, see System Requirements.

Option A: Self-Hosted Deployment

Step 1: Clone and Start Infrastructure

# Clone the repository
git clone https://github.com/treantlab/tamandua.git
cd tamandua

# Start infrastructure (PostgreSQL, Redis, RabbitMQ)
make dev-up

# Setup and run the backend
make backend-setup
make backend-run

The dashboard will be available at http://localhost:4000.

Step 2: Create Your Organization

  1. Open http://localhost:4000 in your browser
  2. Click Sign Up to create an admin account
  3. Create your organization
  4. Navigate to Settings > Agents to generate an enrollment token

Step 3: Deploy Your First Agent

Download the agent for your platform and enroll it through the hidden prompt:

Linux: 
# Download agent
curl -LO https://releases.tamandua.io/agent/latest/tamandua-agent-linux

# Make executable
chmod +x tamandua-agent-linux

# Install and enroll; paste the enrollment token into the hidden prompt
sudo ./tamandua-agent-linux install \
  --server wss://localhost:4000/socket/agent --no-driver
Windows (PowerShell): 
# Download agent
Invoke-WebRequest -Uri "https://releases.tamandua.io/agent/latest/tamandua-agent.exe" -OutFile "tamandua-agent.exe"

# Install and enroll from an Administrator PowerShell; paste the token into the hidden prompt
.\tamandua-agent.exe install --server wss://localhost:4000/socket/agent
macOS Preview/Experimental:

Use macOS only for lab evaluation. Preview builds may not be published for every release and should not be your first production endpoint.

# Download preview agent if available for your release
curl -LO https://releases.tamandua.io/agent/latest/tamandua-agent-macos

# Make executable
chmod +x tamandua-agent-macos

# Preview install; paste the enrollment token into the hidden prompt
sudo ./tamandua-agent-macos install \
  --server wss://localhost:4000/socket/agent --no-driver

Step 4: Verify Agent Connection

  1. Navigate to Dashboard > Agents in your browser
  2. Your new agent should appear with status "Online"
  3. Click the agent to view real-time telemetry

Option B: Building from Source

If you prefer to build everything locally:

# Clone repository
git clone https://github.com/treantlab/tamandua.git
cd tamandua

# Start infrastructure
make dev-up

# Build and run backend
cd apps/tamandua_server
mix deps.get
mix ecto.setup
mix phx.server

# In another terminal, build and run ML service
cd apps/tamandua_ml
uv sync
python -m uvicorn api.main:app --reload

# In another terminal, build the agent
cd apps/tamandua_agent
cargo build --release

# Run the agent
# Foreground development uses an already-issued agent runtime JWT, not an enrollment token.
RUST_LOG=info \
TAMANDUA_SERVER_URL=wss://localhost:4000/socket/agent \
TAMANDUA_TOKEN=<issued-agent-runtime-jwt> \
./target/release/tamandua_agent

Viewing Your First Alert

Once your agent is running, it immediately begins collecting telemetry. To generate a test alert:

Option 1: Wait for Natural Detection

The agent monitors for suspicious behaviors automatically. Normal endpoint activity will generate informational events. Suspicious activity (credential access, persistence, suspicious processes) will trigger alerts.

Option 2: Simulate an Attack (Lab Environment Only)

In a controlled lab environment, you can trigger detection rules:

# Linux - Simulate credential file access
cat /etc/shadow 2>/dev/null || cat ~/.ssh/id_rsa

# Windows PowerShell - Simulate LSASS access attempt
Get-Process lsass
Warning: Only run simulation commands in isolated test environments.

Viewing the Alert

  1. Navigate to Dashboard > Alerts
  2. Click on an alert to view details:

  • Severity and MITRE ATT&CK technique

  • Process tree visualization
  • IOC extraction
  • Timeline of related events

  1. Review alert details and, when enabled for the deployment, privacy-safe attestation data

Verifying Optional On-Chain Proof

For deployments with attestation publishing configured, medium, high, or critical severity alerts can enqueue a privacy-safe Solana attestation. This is optional and depends on the tenant relay or wallet configuration.

Step 1: View Attestation in Dashboard

  1. Click on a qualifying alert (medium+ severity)
  2. Scroll to the attestation section when it is enabled
  3. You will see:

  • Attestation status

  • Transaction ID
  • Solscan link

Step 2: Verify on Solscan

Click the Solscan link to verify the attestation:

https://solscan.io/tx/<transaction-id>?cluster=devnet

You will see:

  • Transaction confirmed on Solana devnet
  • Memo containing privacy-safe attestation data
  • No PII (hostname, username, paths) visible

What the Attestation Contains

{
  "schema": "tamandua.attestation_manifest",
  "version": 2,
  "incident_hash": "a1b2c3...",
  "manifest_hash": "d4e5f6...",
  "severity": "high",
  "mitre_technique": "T1555.003",
  "org_pseudonym": "j0k1l2...",
  "agent_pseudonym": "m3n4o5...",
  "timestamp": "2026-05-08T12:00:00Z",
  "ioc_count": 4,
  "ioc_types": ["hash_sha256", "domain"],
  "tlp": "amber"
}
Privacy guarantee: The attestation proves an incident occurred without revealing sensitive endpoint data.

Configure Solana (Optional)

Attestations require a configured relay or tenant-owned wallet. Some hosted preview environments may provide relay support, but production deployments should treat this as an explicitly enabled integration.

Step 1: Install Solana CLI

# Linux/macOS
sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

# Verify
solana --version

Step 2: Generate Keypair

# Configure for devnet
solana config set --url devnet

# Generate keypair
solana-keygen new --outfile ~/.config/solana/tamandua-devnet.json

# Get devnet SOL
solana airdrop 2 --keypair ~/.config/solana/tamandua-devnet.json

Step 3: Configure Tamandua

Add to your .env:

SOLANA_ENABLED=true
SOLANA_CLUSTER=devnet
SOLANA_RPC_URL=https://api.devnet.solana.com
SOLANA_KEYPAIR_PATH=/home/user/.config/solana/tamandua-devnet.json
SOLANA_ATTESTATION_MODE=memo

Restart the backend to apply changes.

Next Steps

Congratulations! You have:

  • Deployed your first Tamandua agent
  • Connected it to your server
  • Viewed security events in the dashboard
  • Verified a privacy-safe on-chain proof

Continue Learning

  • System Requirements - Full hardware and software prerequisites
  • Architecture - Deep dive into components and security model
  • Detection Rules - Learn to write custom YARA and Sigma rules
  • Response Playbooks - Automate incident response

Production Deployment

For production deployments:

  1. Enable mTLS authentication (see Security documentation)
  2. Configure proper TLS certificates
  3. Set up database backups
  4. Configure log retention policies
  5. Review the Security Architecture guide

Troubleshooting

Agent Won't Connect

Check the following:

# Enable debug logging
RUST_LOG=debug ./tamandua-agent

# Verify server is running
curl http://localhost:4000/health

# Check token validity
# Tokens expire after 24 hours by default

No Alerts Appearing

  • Verify agent is online in Dashboard > Agents
  • Check agent logs for detection events
  • Try simulating activity in a lab environment
  • Ensure detection rules are loaded

Attestation Not Created

  • Only medium/high/critical alerts trigger attestations
  • Check Solana configuration in server logs
  • Verify devnet RPC is accessible:

  curl https://api.devnet.solana.com -X POST \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"getHealth"}'

Build Failures

# Rust agent - check dependencies
cd apps/tamandua_agent
cargo check

# Elixir backend - fetch dependencies
cd apps/tamandua_server
mix deps.get
mix compile

# Python ML - sync environment
cd apps/tamandua_ml
uv sync

Quick Reference

ActionCommand
Start infrastructuremake dev-up
Run backendmake backend-run
Build agentmake agent-build
Run agentmake agent-run
View logsmake logs
Run testsmake test
Stop allmake dev-down
Last updated: May 2026