Setup Guide

June 7, 2026 · View on GitHub

Complete installation, authentication, and configuration reference.

System Requirements
Installation
Authentication Methods
Supported Providers
Model Profiles
Web Dashboard
CLI Reference
Agentic Setup — End-to-End Walkthrough
Advanced Configuration
Troubleshooting

System Requirements

Requirement	Minimum	Recommended
OS	Linux (x86_64, arm64), macOS (arm64, x86_64), WSL2 on Windows	Ubuntu 22.04+ / Kali 2024+ / macOS 14+ / WSL2 with Ubuntu or Kali
Container runtime	Docker Engine 24+ with Compose v2 OR Podman 4.4+ with `podman compose` OR nerdctl with compose plugin	Docker Desktop / Colima / Podman Desktop
RAM	8 GB	16 GB
Disk	10 GB free	20 GB free
Network	Outbound HTTPS	Low-latency connection

Docker is the only hard dependency. Everything else runs in containers.

Supported environments

OSS install targets and what we test against:

Environment	Launcher binary	Notes
macOS arm64 (Apple Silicon, M1–M4)	`darwin/arm64`	Native. Every container image is published multi-arch (linux/amd64 + linux/arm64), so Docker Desktop pulls the arm64 manifest and runs without Rosetta.
macOS amd64 (Intel)	`darwin/amd64`	Native.
Linux amd64 (Ubuntu, Debian, Fedora, Kali)	`linux/amd64`	Native.
Linux arm64 (Raspberry Pi 5, Ampere, AWS Graviton, Asahi)	`linux/arm64`	Native — same multi-arch images as Apple Silicon.
WSL2 (Windows + Ubuntu/Kali on WSL2)	`linux/amd64`	Use Docker Desktop with the WSL2 backend, or install Docker natively inside the WSL distro. See WSL2 notes below.
Windows amd64 (Windows 10/11, native)	`windows/amd64`	Native. Install via `irm https://decepticon.red/install.ps1 \| iex` in PowerShell. Requires Docker Desktop.
Windows arm64 (Surface Pro X, ARM laptops)	`windows/arm64`	Native. Same PowerShell installer.

Native Windows is supported alongside WSL2 — choose whichever fits your toolchain. The Go launcher detects the OS during decepticon onboard and adapts its remediation hints (Docker Desktop install URL, daemon-not-running fix, missing Compose v2).

WSL2 notes

Decepticon runs end-to-end on WSL2 with two valid Docker setups:

Docker Desktop with WSL2 backend (the common path) — Docker Desktop registers host.docker.internal automatically.
Native Docker inside the WSL distro (no Docker Desktop) — Decepticon's docker-compose.yml adds the host.docker.internal:host-gateway mapping itself, so containers reach the host either way.

The default OLLAMA_API_BASE=http://host.docker.internal:11434 is the right value in all environments — including the case where Ollama runs inside the same WSL distro as Decepticon. From inside a container, localhost is the container itself, so it can never reach Ollama on the host. Use host.docker.internal.

Ollama must additionally listen on all interfaces — the default 127.0.0.1 binding is invisible to containers. Launch it with:

OLLAMA_HOST=0.0.0.0:11434 ollama serve

Other WSL caveats:

Install Decepticon under your WSL home (~/.decepticon), not on a Windows-mounted drive (/mnt/c/...) — bind-mounted I/O across the boundary is much slower.
WSL2 mirrored networking (Windows 11 22H2+) collapses the Windows host ↔ WSL distro split, but Docker bridge networks remain isolated. The host.docker.internal requirement still applies.

WSL2 + Ollama troubleshooting flowchart

If OLLAMA_API_BASE=http://host.docker.internal:11434 is failing from the litellm container on WSL2, work through these checks in order. The [decepticon ollama] log lines in decepticon logs litellm will identify which class of failure you're hitting; this section names each class and its fix.

1. Class: connection refused — Ollama is up but bound to 127.0.0.1 only. The litellm container sees host.docker.internal resolve fine, then the TCP handshake gets RST.

Verify from the WSL host (NOT inside the container):

netstat -tlnp 2>/dev/null | grep 11434
# Expected: tcp 0 0 0.0.0.0:11434 0.0.0.0:* LISTEN <pid>/ollama
# Wrong:    tcp 0 0 127.0.0.1:11434 0.0.0.0:* LISTEN <pid>/ollama

Fix:

# Foreground / current shell only
OLLAMA_HOST=0.0.0.0:11434 ollama serve

# Persist across reboots — systemd unit override
sudo mkdir -p /etc/systemd/system/ollama.service.d
sudo tee /etc/systemd/system/ollama.service.d/override.conf <<'EOF'
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
EOF
sudo systemctl daemon-reload && sudo systemctl restart ollama

2. Class: DNS not resolved — host.docker.internal doesn't resolve inside the container. Common with native Docker in WSL when the extra_hosts mapping is missing (e.g. a stale compose override).

Verify from inside the container:

decepticon exec litellm getent hosts host.docker.internal
# Expected: 172.x.x.1  host.docker.internal
# Wrong:    (no output)

Fix: confirm docker-compose.yml litellm service has:

    extra_hosts:
      - "host.docker.internal:host-gateway"

Workaround (if your override removed it): pin WSL distro IP in .env:

WSL_IP=$(ip -4 addr show eth0 | awk '/inet / {print \$2}' | cut -d/ -f1)
echo "OLLAMA_API_BASE=http://$WSL_IP:11434" >> ~/.decepticon/.env

Note: the WSL IP changes across reboots. Prefer fixing the bridge resolution.

3. Class: request timed out — Host resolves, port not answering. Two sub-cases:

Windows Defender Firewall blocks inbound 11434. Check in Windows admin PowerShell:

Get-NetFirewallRule -Direction Inbound |
  Where DisplayName -like '*Ollama*' |
  Format-Table DisplayName, Enabled, Profile

Fix:

New-NetFirewallRule -DisplayName 'Ollama for WSL2' `
  -Direction Inbound -LocalPort 11434 -Protocol TCP -Action Allow

WSL2 mirrored networking misconfigured. On Windows 11 22H2+ mirrored mode requires ~/.wslconfig (Windows-side):
```
[wsl2]
networkingMode=mirrored
```
Apply via wsl --shutdown then restart your distro. After mirrored mode is active, OLLAMA_API_BASE=http://localhost:11434 may work directly from the litellm container.

4. Class: model not pulled — /api/show returns 404 for OLLAMA_MODEL. Probe surfaces: "Ollama model X is not pulled on this host." Fix: ollama pull <model>.

5. Class: model doesn't support tools — /api/show capabilities don't include tools. Pick a tool-capable model: qwen3-coder, llama3.3, mistral-small3, deepseek-r1.

One-shot diagnostic

Run the probe directly inside the litellm container:

docker exec -e OLLAMA_API_BASE=$OLLAMA_API_BASE \
  -e OLLAMA_MODEL=$OLLAMA_MODEL \
  $(docker ps -qf name=litellm | head -1) \
  python3 -c "
from config.ollama_probe import probe
for line in probe('$OLLAMA_API_BASE', ['ollama_chat/$OLLAMA_MODEL']):
    print(line)
"

Each line is one operator-actionable hint. The probe now detects WSL2 environments (via /proc/version and WSL_* env vars) and emits WSL2-specific guidance for every error class.

Installation

One-Line Install

curl -fsSL https://decepticon.red/install | bash

This downloads the decepticon CLI binary for your platform and places it in your PATH.

Using Podman instead of Docker

Decepticon detects Podman 4.4+ automatically. The launcher prefers Docker when both are available; set DECEPTICON_CONTAINER_RUNTIME=podman to force Podman:

# Linux (rootless Podman, recommended)
systemctl --user enable --now podman.socket          # enable the API socket
export DECEPTICON_CONTAINER_RUNTIME=podman           # force Podman selection
decepticon start                                      # launcher detects + uses podman compose

What the launcher handles for you:

Selects podman if docker is absent (or if you set the override).
Auto-discovers the Podman API socket ($XDG_RUNTIME_DIR/podman/podman.sock or /run/user/$UID/podman/podman.sock for rootless; /run/podman/podman.sock for rootful) and exports DOCKER_HOST so any nested Docker-API tooling (testcontainers, etc.) keeps working.
Uses podman compose (Podman 4.4+ built-in); falls back to the podman-compose Python wrapper on older Podman.

Rootless Podman caveats:

The c2-sliver profile binds privileged ports (443, 53). On rootless Podman you need either sudo setcap CAP_NET_BIND_SERVICE=+eip $(which podman) or add net.ipv4.ip_unprivileged_port_start = 53 to /etc/sysctl.conf. Or just run rootful.
Bind mounts under your home directory work transparently. Mounting /var/run/... requires --security-opt label=disable on SELinux distros (Fedora, RHEL).

Using nerdctl

export DECEPTICON_CONTAINER_RUNTIME=nerdctl
decepticon start

Requires nerdctl ≥ 0.16 (built-in compose) and a running containerd (containerd or Rancher Desktop with the containerd engine).

Manual Install (from source)

make dogfood reproduces the OSS launcher flow against locally-built images — launcher onboard wizard, engagement picker, compose up, health checks, and the CLI all execute exactly as the curl | bash install path. The launcher and every service image come from the current checkout (tag :dev), with an isolated $DECEPTICON_HOME under .dogfood/ so your real ~/.decepticon is untouched.

git clone https://github.com/PurpleAILAB/Decepticon.git
cd Decepticon
make dogfood

Verify Installation

decepticon version

Authentication Methods

Decepticon supports three authentication modes. Choose one during decepticon onboard.

API Keys

Standard pay-per-token access through provider APIs. Set the appropriate environment variable for your provider.

decepticon onboard
# Select: API Key
# Select: Your provider
# Enter: Your API key

Or edit ~/.decepticon/.env directly:

DECEPTICON_AUTH_PRIORITY=anthropic_api,openai_api
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENAI_API_KEY=sk-proj-...

All supported API key providers:

Provider	Env Var	Key Format	Sign Up
Anthropic	`ANTHROPIC_API_KEY`	`sk-ant-...`	console.anthropic.com
OpenAI	`OPENAI_API_KEY`	`sk-proj-...`	platform.openai.com
DeepSeek	`DEEPSEEK_API_KEY`	`sk-...`	platform.deepseek.com
Google	`GEMINI_API_KEY`	`AIza...`	aistudio.google.com
xAI	`XAI_API_KEY`	`xai-...`	console.x.ai
Mistral	`MISTRAL_API_KEY`	`...`	console.mistral.ai
Cohere	`COHERE_API_KEY`	`...`	dashboard.cohere.com
Groq	`GROQ_API_KEY`	`gsk_...`	console.groq.com
Together	`TOGETHER_API_KEY`	`...`	api.together.xyz
Fireworks	`FIREWORKS_API_KEY`	`fw_...`	fireworks.ai
Perplexity	`PERPLEXITY_API_KEY`	`pplx-...`	perplexity.ai
MiniMax	`MINIMAX_API_KEY`	`eyJ...`	minimax.io
OpenRouter	`OPENROUTER_API_KEY`	`sk-or-...`	openrouter.ai
Replicate	`REPLICATE_API_TOKEN`	`r8_...`	replicate.com
NVIDIA NIM	`NVIDIA_API_KEY`	`nvapi-...`	build.nvidia.com
Moonshot (Kimi K2)	`MOONSHOT_API_KEY`	`sk-...`	platform.moonshot.cn
Z.ai (GLM-4.5)	`ZAI_API_KEY`	`...`	z.ai/manage
Alibaba DashScope (Qwen)	`DASHSCOPE_API_KEY`	`sk-...`	dashscope.console.aliyun.com
GitHub Models	`GITHUB_TOKEN`	`github_pat_...`	github.com/settings/personal-access-tokens

Cloud platform providers:

Provider	Required Env Vars
Azure OpenAI	`AZURE_API_KEY`, `AZURE_API_BASE`, `AZURE_API_VERSION`
AWS Bedrock	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`
GCP Vertex AI	`GOOGLE_APPLICATION_CREDENTIALS`, `VERTEXAI_PROJECT`, `VERTEXAI_LOCATION`

Self-hosted / OpenAI-compatible:

Provider	Required Env Vars
Ollama (local)	`OLLAMA_API_BASE` + `OLLAMA_MODEL` — see Local LLM (Ollama) below
Ollama Cloud	`OLLAMA_CLOUD_API_BASE`, `OLLAMA_CLOUD_API_KEY`, `OLLAMA_CLOUD_MODEL`
LM Studio (local)	`LMSTUDIO_API_BASE` + `LMSTUDIO_MODEL` (server on port 1234)
Custom gateway	`CUSTOM_OPENAI_API_KEY`, `CUSTOM_OPENAI_API_BASE`, `CUSTOM_OPENAI_MODEL`

OpenAI-compatible gateways / aggregators:

Each routes through LiteLLM's openai/ provider with a fixed base URL (no extra config beyond the key). Set the key and the gateway joins the default fallback chain; pick a specific route at runtime with /model (e.g. /model opencode/claude-opus-4-6).

Provider	Env Var	Console
OpenCode Zen	`OPENCODE_API_KEY`	opencode.ai/docs/zen
Vercel AI Gateway	`VERCEL_AI_GATEWAY_API_KEY`	vercel.com/docs/ai-gateway
Hugging Face Router	`HF_TOKEN`	huggingface.co/settings/tokens
Venice AI	`VENICE_API_KEY`	venice.ai/settings/api
NanoGPT	`NANOGPT_API_KEY`	nano-gpt.com
Synthetic	`SYNTHETIC_API_KEY`	synthetic.new
ZenMux	`ZENMUX_API_KEY`	zenmux.ai
Baidu Qianfan (ERNIE)	`QIANFAN_API_KEY`	console.bce.baidu.com/qianfan
Cloudflare AI Gateway	`CLOUDFLARE_AI_GATEWAY_API_KEY` + `CLOUDFLARE_AI_GATEWAY_API_BASE`	dash.cloudflare.com

Cloudflare's base URL is per-account — set it to your gateway's OpenAI-compat …/compat path. Qianfan model ids drift; override per role with DECEPTICON_MODEL_<ROLE> if a default 404s.

Local LLM (Ollama)

Run Decepticon offline against a local Ollama server — no cloud API billing, no key.

Setup:

Install Ollama on your host: https://ollama.com/download.
Pull a tool-capable model — Decepticon agents always call tools, so the chosen model must advertise the tools capability. Known working families: Qwen3-Coder, Llama 3.3, DeepSeek-R1, Mistral Small 3, Hermes-3:
```
ollama pull qwen3-coder:30b
ollama show qwen3-coder:30b   # capabilities should include "tools"
```
Start the Ollama server bound to all interfaces so the Decepticon container can reach it (the default 127.0.0.1 binding only accepts host-side connections):
```
OLLAMA_HOST=0.0.0.0:11434 ollama serve
```
On systems where Ollama runs as a service (e.g. systemd), set Environment=OLLAMA_HOST=0.0.0.0:11434 in the unit and restart it.
Run decepticon onboard and pick "Local LLM (Ollama)". The wizard prompts for:
- OLLAMA_API_BASE — leave the default http://host.docker.internal:11434. This works on macOS, Linux, and WSL2 (with or without Docker Desktop) because docker-compose.yml adds the host.docker.internal:host-gateway mapping. localhost is never the right answer — from inside a container that's the container itself, not the host.
- OLLAMA_MODEL — the wizard probes your running Ollama at the default URL, lists every pulled model whose /api/show capabilities include tools, and presents that filtered list as the only valid choice. You cannot type a tag manually: Decepticon agents always emit tool calls, so a non-tool-capable model would break on the first request. If the wizard finds nothing tool-capable (or cannot reach Ollama), it refuses to write .env and prints the exact remediation steps.
Run decepticon. A second probe inside the litellm container re-verifies reachability and tool-capability after the stack starts — the in-wizard host probe can't tell whether Ollama is bound to 0.0.0.0 (visible to the container) versus 127.0.0.1 only (invisible). Either probe failing prints a clear diagnostic in decepticon logs litellm.

How it works:

LiteLLM dynamically registers ollama_chat/<OLLAMA_MODEL> at proxy startup (config/litellm_dynamic_config.py). No yaml edit needed.
ollama_chat/ (not ollama/) routes to Ollama's /api/chat endpoint — the only one that supports tool/function calling, which every Decepticon agent depends on.
The ollama_local AuthMethod collapses HIGH/MID/LOW tiers to the same model — local hardware can't usually run three different models in parallel. Mix with cloud providers if you want tier degradation: set DECEPTICON_AUTH_PRIORITY=ollama_local,anthropic_api to lead with local and fall back to Anthropic on local-side errors.

Per-role overrides:

If you do have the GPU headroom, override individual agents to different Ollama models without touching yaml:

DECEPTICON_MODEL_DECEPTICON=ollama_chat/qwen3-coder:30b   # HIGH agents
DECEPTICON_MODEL_RECON=ollama_chat/llama3.2:3b             # LOW agents

The dynamic config registrar picks these up at startup.

Claude Max/Pro Subscription (OAuth)

Use your Claude Max, Pro, or Team subscription instead of API billing. Requests route through Claude Code's OAuth handler — no API cost.

Supported tiers:

Tier	Models Available	Rate Limits
Claude Free	Haiku only	Very limited
Claude Pro ($20/mo)	Opus, Sonnet, Haiku	Standard
Claude Max ($100/mo)	Opus, Sonnet, Haiku	20x higher
Claude Team	Opus, Sonnet, Haiku	Organization-managed

Setup:

Install Claude Code CLI and authenticate:

# Install Claude Code (if not already installed)
npm install -g @anthropic-ai/claude-code

# Authenticate — opens browser for OAuth login
claude login

Verify credentials exist:

cat ~/.claude/.credentials.json
# Should contain claudeAiOauth.accessToken starting with sk-ant-oat01-

Configure Decepticon to use OAuth:

decepticon onboard
# Select: Claude Sub
# Select: Claude Code
# Select: Profile (eco/max/test)

Or edit ~/.decepticon/.env:

DECEPTICON_AUTH_PRIORITY=anthropic_oauth,anthropic_api
DECEPTICON_AUTH_CLAUDE_CODE=true
DECEPTICON_MODEL_PROFILE=eco

Launch:

decepticon

How it works:

The auth provider remaps anthropic/* model names to auth/*
LiteLLM routes auth/* through claude_code_handler.py
The handler reads OAuth tokens from ~/.claude/.credentials.json
Requests hit api.anthropic.com with Bearer auth + Claude Code headers
Tokens auto-refresh when expired using the stored refresh token
Fallback models stay on API-key provider for redundancy

Alternative token sources (in priority order):

ANTHROPIC_OAUTH_TOKEN env var — direct access token
~/.claude/.credentials.json — Claude Code CLI (current format)
~/.config/anthropic/q/tokens.json — Legacy format

Custom credentials path:

CLAUDE_CODE_CREDENTIALS_PATH=/custom/path/credentials.json

ChatGPT Pro/Plus Subscription (OAuth)

Use your ChatGPT Pro, Plus, or Team subscription instead of OpenAI API billing.

Supported tiers:

Tier	Models Available (via `auth/gpt-5.x` route)
ChatGPT Plus ($20/mo)	`auth/gpt-5.5`, `auth/gpt-5.4`, `auth/gpt-5.4-mini`
ChatGPT Pro ($200/mo)	`auth/gpt-5.5`, `auth/gpt-5.4`, `auth/gpt-5.4-mini`
ChatGPT Team	`auth/gpt-5.5`, `auth/gpt-5.4`, `auth/gpt-5.4-mini` + admin controls

Setup:

Configure Decepticon:

decepticon onboard
# Select: ChatGPT
# Select: Profile (eco/max/test)

Or edit ~/.decepticon/.env:

DECEPTICON_AUTH_CHATGPT=true

Launch:

decepticon

How it works:

Decepticon exposes ChatGPT subscription models as auth/gpt-5.5 and auth/gpt-5.4.
LiteLLM dynamic config maps those aliases through Decepticon's custom auth/ handler (codex_chatgpt_handler) only when DECEPTICON_AUTH_CHATGPT=true.
docker-compose.yml mounts the host's Codex CLI credential file (~/.codex/auth.json) into the LiteLLM container at /root/.codex/auth.json (read-write, so the in-container refresh path can persist rotated tokens back to the host).
The auth/ handler reads and writes the same auth.json the Codex CLI itself uses, so a host-side codex login is visible to the running container without a restart, and a refresh inside the container is visible to the host CLI on the next call.

Setup:

# Install the Codex CLI and run the device-code login on the host:
codex login
# Confirm the file exists:
ls ~/.codex/auth.json

Google Gemini Advanced (OAuth)

Use your Google One AI Premium subscription ($20/mo).

Setup:

Extract OAuth token from gemini.google.com browser session, or use Google Cloud OAuth2 credentials
Configure:

DECEPTICON_AUTH_GEMINI=true
GEMINI_ACCESS_TOKEN=<your-google-oauth-token>

Or use session cookies:

GEMINI_SESSION_COOKIES={"__Secure-1PSID":"value","__Secure-1PSIDTS":"value"}

Token file: ~/.config/gemini/tokens.json

Microsoft Copilot Pro (OAuth)

Use your Copilot Pro subscription ($20/mo) for GPT-4o/o1 access.

Setup:

Extract tokens from copilot.microsoft.com browser session
Configure:

DECEPTICON_AUTH_COPILOT=true
COPILOT_ACCESS_TOKEN=eyJ...your-ms-token

Or with auto-refresh:

COPILOT_REFRESH_TOKEN=M.C507_BAY...
COPILOT_CLIENT_ID=your-app-client-id

Token file: ~/.config/copilot/tokens.json

xAI SuperGrok (OAuth)

Use your X Premium+ subscription for Grok-3 access.

Setup:

Extract auth_token cookie from grok.x.ai or x.com
Configure:

DECEPTICON_AUTH_GROK=true
GROK_SESSION_TOKEN=your-x-auth-token

Token file: ~/.config/grok/tokens.json

Perplexity Pro (OAuth)

Use your Perplexity Pro subscription ($20/mo) for Sonar Pro access.

Setup:

Extract next-auth.session-token cookie from perplexity.ai
Configure:

DECEPTICON_AUTH_PERPLEXITY=true
PERPLEXITY_SESSION_TOKEN=your-session-token

Token file: ~/.config/perplexity/tokens.json

Supported Providers

Complete list of all supported LLM providers and their pre-configured models:

Provider	Models	Auth Type	Cost
Subscriptions (OAuth — no API billing)
Claude Max/Pro/Team	Opus, Sonnet, Haiku	OAuth	$20–$100/mo
ChatGPT Pro/Plus/Team	`auth/gpt-5.5`, `auth/gpt-5.4`, `auth/gpt-5.4-mini` (+ `auth/gpt-5.3-codex` for code agents)	OAuth	$20–$200/mo
Gemini Advanced	Gemini 2.5 Pro/Flash	OAuth	$20/mo
Copilot Pro	`copilot/gpt-5.5`, `copilot/claude-sonnet-4-6`, `copilot/gpt-5.4-mini` (+ `copilot/gpt-5.3-codex`)	OAuth	$20/mo
SuperGrok	Grok 4.3, Grok 4-1 Fast Reasoning	OAuth	X Premium+
Perplexity Pro	Sonar Pro, Sonar	OAuth	$20/mo
API Key Providers (pay-per-token)
Anthropic	Claude Opus 4.7, Sonnet 4.6, Haiku 4.5	API key	Per token
OpenAI	GPT-5.5, GPT-5.4, GPT-5-nano (+ GPT-5.3-Codex for code agents)	API key	Per token
DeepSeek	DeepSeek Chat, DeepSeek Reasoner	API key	Per token
Google	Gemini 2.5 Flash, Gemini 2.5 Pro	API key	Per token
xAI	Grok 4.3, Grok 4-1 Fast Reasoning	API key	Per token
Mistral	Mistral Large, Codestral	API key	Per token
Cohere	Command R+, Command R	API key	Per token
Groq	Llama 3.3 70B, Llama 3.1 8B	API key	Per token
Together AI	Llama 3.3 70B Turbo + any	API key	Per token
Fireworks AI	Llama 405B + any	API key	Per token
Perplexity	Sonar Pro, Sonar	API key	Per token
MiniMax	MiniMax-M3, MiniMax-M2.7-highspeed	API key	Per token
OpenRouter	Any model via routing	API key	Per token
Azure OpenAI	Any Azure-deployed model	API key + endpoint	Per token
AWS Bedrock	Any Bedrock model	AWS credentials	Per token
Replicate	Any Replicate-hosted model	API token	Per token
Self-Hosted
Ollama	Any locally-served model	Local endpoint	Free
Custom Gateway	Any OpenAI-compatible server	API key + base URL	Varies

Adding models not in the static config:

Set DECEPTICON_MODEL or DECEPTICON_LITELLM_MODELS and Decepticon auto-generates the LiteLLM route at container startup:

DECEPTICON_MODEL_PROFILE=custom
DECEPTICON_MODEL=openrouter/anthropic/claude-3.7-sonnet
DECEPTICON_LITELLM_MODELS=groq/llama-3.3-70b-versatile,together/deepseek-ai/DeepSeek-R1

Model Profiles

Profile	Use Case	Cost
`eco`	Production engagements — balanced mix	$$
`max`	High-value targets — Opus everywhere	$$$$
`test`	Development and CI — Haiku only	$
`custom`	Bring your own model via `DECEPTICON_MODEL`	Varies

Set in ~/.decepticon/.env:

DECEPTICON_MODEL_PROFILE=eco

Per-role overrides (any profile):

DECEPTICON_MODEL_RECON=ollama_chat/qwen3-coder:30b
DECEPTICON_MODEL_EXPLOIT=anthropic/claude-opus-4-7
DECEPTICON_MODEL_EXPLOIT_TEMPERATURE=0.2

See Models for the full role-to-model mapping.

Web Dashboard

The web dashboard starts automatically with decepticon and is accessible at:

http://localhost:3000

Features:

Real-time engagement monitoring
Agent activity and conversation timeline
Attack chain visualization (Neo4j knowledge graph)
Model usage and cost tracking
Terminal access to the sandbox environment

Custom port:

# In ~/.decepticon/.env
WEB_PORT=8080

See Web Dashboard for the full feature reference.

CLI Reference

Core Commands

decepticon                  # Launch platform (all services + interactive CLI)
decepticon onboard          # Setup wizard (auth, provider, profile)
decepticon onboard --reset  # Re-run setup from scratch
decepticon stop             # Stop all services, keep data
decepticon status           # Show running services
decepticon logs [service]   # Follow service logs
decepticon update           # Explicitly refresh config/images and upgrade when available
decepticon remove           # Uninstall Decepticon completely
decepticon --version        # Show installed version

Service Management

decepticon logs litellm     # LiteLLM proxy logs
decepticon logs langgraph   # LangGraph agent logs
decepticon logs neo4j       # Knowledge graph logs
decepticon kg-health        # Neo4j connection diagnostics

See CLI Reference for the complete command list.

Agentic Setup — End-to-End Walkthrough

Complete walkthrough from zero to a running autonomous engagement, covering every component.

Step 1: Install the CLI

# One-line install (Linux/macOS)
curl -fsSL https://decepticon.red/install | bash

# Or from source
git clone https://github.com/PurpleAILAB/Decepticon.git
cd Decepticon
make install

Verify:

decepticon version

Step 2: Run the Setup Wizard

decepticon onboard

The wizard walks through 6 screens:

Step	Screen	What you configure
1	Authentication	API Key, Claude Sub, ChatGPT Sub, Gemini Sub, Copilot Pro, SuperGrok, or Perplexity Pro
2	Provider	Which LLM provider powers the agents (18+ options)
3	Credentials	API key, OAuth token, or endpoint URL
4	Model	Primary model ID (auto-detected for Anthropic presets)
5	Profile	`eco` (balanced), `max` (performance), `test` (dev), `custom` (any model)
6	Observability	Optional LangSmith tracing

Configuration saves to ~/.decepticon/.env. Re-run anytime with decepticon onboard --reset.

Step 3: Launch the Platform

decepticon

This single command:

Validates your .env configuration
Pulls Docker images (first run only, ~2 GB)
Starts 7 services in dependency order:
- PostgreSQL → LiteLLM proxy → Neo4j → Sandbox → LangGraph → Web Dashboard → CLI
Waits for all healthchecks to pass (~60-120s first run, ~10s subsequent)
Shows the engagement picker
Launches the interactive terminal CLI

Step 4: Service Architecture

Once running, you have:

Service	Port	Purpose
LiteLLM	4000	LLM API gateway — routes to providers, tracks usage, handles fallback
LangGraph	2024	Agent runtime — hosts all 17 agents as a streaming API
Neo4j	7474/7687	Knowledge graph — persistent attack chain memory
Sandbox	(internal)	Isolated Kali Linux — runs all offensive tools
Web Dashboard	3000	Browser UI — real-time monitoring, graph visualization
Terminal Server	3003	WebSocket bridge — embeds CLI in the web dashboard
PostgreSQL	5432	Persistence — LiteLLM usage logs, web dashboard data

Step 5: Create Your First Engagement

Option A — Terminal CLI:

# Decepticon shows the engagement picker after launch
# Select "New engagement" → type a slug → Soundwave starts interviewing you

Option B — Web Dashboard:

Open http://localhost:3000
Click "New Engagement"
Enter: name, target type (IP range, URL, Git repo, file, local path), target value
Click "Create" → opens the live terminal with Soundwave

Step 6: The Soundwave Interview

Soundwave conducts a structured interview to generate the engagement package:

Questions you'll answer:
├── Target scope (IPs, URLs, domains)
├── Threat actor profile (nation-state, criminal, insider)
├── Authorized actions (scanning, exploitation, lateral movement)
├── Exclusions (production DBs, critical infra)
├── Testing window (hours, days, timezone)
├── OPSEC requirements (noise level, detection avoidance)
└── Acceptance criteria (what does "done" look like)

Soundwave generates an eight-document engagement bundle from your answers:

Document	Purpose
RoE	Legal authorization, scope, exclusions, escalation contacts
Threat Profile	MITRE-mapped adversary persona and key TTPs
CONOPS	Threat model and kill-chain phases, scoped to the RoE
Deconfliction Plan	Source IPs, time windows, SOC coordination codes
Contact Plan	Operator and escalation roster, plus the abort-signal recipient
Data Handling Plan	Evidence retention, encryption, and chain-of-custody
Abort Plan	Halt triggers and AI-aware safety gates
Cleanup Plan	Expected artifacts and per-phase removal commands

The orchestrator builds the OPPLAN (objectives, phases, MITRE ATT&CK mapping) from the bundle — Soundwave does not write it.

Step 7: Autonomous Execution

After you approve the OPPLAN, Decepticon takes over:

Decepticon (Orchestrator)
├── Reads OPPLAN objectives
├── Dispatches to specialist agents:
│   ├── Recon → port scan, service enum, OSINT
│   ├── Scanner → vulnerability scanning, CVE mapping
│   ├── Exploit → initial access, payload delivery
│   ├── Post-Exploit → privesc, lateral movement, C2
│   ├── AD Operator → Active Directory attack chains
│   └── Cloud Hunter → cloud infrastructure attacks
├── Tracks progress in Neo4j knowledge graph
├── Adapts strategy based on findings
└── Generates final report via Analyst agent

All commands execute inside the sandboxed Kali container — zero host exposure.

Step 8: Monitor in Real Time

Terminal CLI:

Live streaming of agent activity, tool calls, sub-agent dispatch
Ctrl+O to toggle transcript mode (full event history)
Ctrl+C to pause (resume with /resume)

Web Dashboard (http://localhost:3000):

Live attack graph visualization (Neo4j-backed)
Agent activity timeline
OPPLAN progress tracker
Findings table with severity ratings
Embedded terminal (same CLI, in-browser)

Step 9: Post-Engagement

# View findings
ls ~/.decepticon/workspace/<engagement>/findings/

# View generated documents
ls ~/.decepticon/workspace/<engagement>/plan/

# Export knowledge graph
decepticon logs neo4j

# Stop services (preserves data)
decepticon stop

# Full reset (removes all data)
cd ~/.decepticon && docker compose down -v

Quick Reference — Common Workflows

Resume a previous engagement:

decepticon           # Shows engagement picker → select existing
# Or from CLI: /resume → select from session list

Switch model provider mid-session:

decepticon stop
# Edit ~/.decepticon/.env → change DECEPTICON_AUTH_PRIORITY, DECEPTICON_AUTH_* toggles, or API keys
decepticon

Check service health:

decepticon status       # Container status (docker compose ps)
decepticon kg-health    # Knowledge graph diagnostics (LangGraph + Neo4j connection)

View logs for specific service:

decepticon logs              # LangGraph (default)
decepticon logs litellm      # LLM proxy
decepticon logs neo4j        # Knowledge graph
decepticon logs web          # Web dashboard

Advanced Configuration

Multiple API Keys

You can configure multiple providers simultaneously. The model profile controls which is used for each agent role, and fallbacks automatically use the next provider:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-proj-...
DEEPSEEK_API_KEY=sk-...
GEMINI_API_KEY=AIza...

Hybrid Auth (OAuth + API Keys)

Set DECEPTICON_AUTH_CLAUDE_CODE=true to route Anthropic models through Claude Code OAuth while keeping API-key fallbacks active. The DECEPTICON_AUTH_PRIORITY list controls order:

DECEPTICON_AUTH_PRIORITY=anthropic_oauth,anthropic_api,openai_api,google_api
DECEPTICON_AUTH_CLAUDE_CODE=true      # Primary: Claude via OAuth (auth/* in LiteLLM)
ANTHROPIC_API_KEY=sk-ant-...          # Fallback: Anthropic API
OPENAI_API_KEY=sk-proj-...            # Fallback: GPT via API key
GEMINI_API_KEY=AIza...                # Fallback: Gemini via API key

LangSmith Tracing

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=decepticon

Custom Ports

LANGGRAPH_PORT=2024   # Agent runtime
LITELLM_PORT=4000     # LLM proxy
POSTGRES_PORT=5432    # Database
WEB_PORT=3000         # Dashboard

Debug Mode

DECEPTICON_DEBUG=true

Troubleshooting

Authentication Issues

Claude OAuth: "No Claude Code OAuth tokens found"

# Re-authenticate Claude Code CLI
claude login

# Verify token exists
cat ~/.claude/.credentials.json | python3 -c "import sys,json; d=json.load(sys.stdin); print('OK' if d.get('claudeAiOauth',{}).get('accessToken','').startswith('sk-ant-oat01-') else 'MISSING')"

ChatGPT OAuth: missing or expired auth

The Decepticon auth/ ChatGPT handler reads the Codex CLI credential store at ~/.codex/auth.json. If the file is missing or the refresh token is rejected, run codex login on the host and retry. The handler picks up the refreshed file automatically (no container restart needed).

API Key: "401 Unauthorized"

# Verify key format
grep _API_KEY ~/.decepticon/.env | head -5

# Test directly
curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-haiku-4-5-20251001","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

Docker Issues

Apple Silicon (M1/M2/M3/M4): "no matching manifest for linux/arm64/v8"

Every container image is published multi-arch (linux/amd64 + linux/arm64), so this error should not reproduce on a fresh install. If you do hit it, you're almost certainly running an old docker-compose.yml from a previous install.

Solution: pull the latest config files:

decepticon update

If your host arch is not amd64 or arm64 (rare — armv7, ppc64le, ...), the manifest list won't match. Force the amd64 fallback by adding platform: linux/amd64 under the sandbox: and c2-sliver: services in ~/.decepticon/docker-compose.yml and enable "Use Rosetta for x86_64/amd64 emulation" in Docker Desktop settings (or QEMU on Linux).

Services won't start:

decepticon status          # Which services are down?
decepticon logs litellm    # Check LiteLLM for config errors
docker compose ps          # Raw container status

LiteLLM can't reach provider:

# Check inside the container
docker compose exec litellm curl -s https://api.anthropic.com/v1/messages -I

Neo4j connection refused:

decepticon kg-health

Reset Everything

decepticon stop
cd ~/.decepticon && docker compose down -v   # Remove all volumes
decepticon onboard --reset                    # Re-run setup
decepticon                                    # Fresh start