Skip to main content

​
Install from PyPI

Decepticon is published as a Python package. Install the core SDK: 
pip install decepticon              # core SDK
pip install "decepticon[neo4j]"     # + the knowledge-graph attack-chain tools
decepticon is a client SDK, not a standalone app. It ships the agent factories, middleware, tools, and skills — but LLM calls and sandbox execution are routed to runtime services over HTTP. To actually run agents you also need those services (the Docker stack, or your own endpoints).

​
The two tiers

TierWhatHow it ships
SDK (this package)decepticon/ — agent factories, middleware, tools, backends, the llm factory, and skills (bundled as package data)PyPI wheel — pip install decepticon
Runtime servicesLiteLLM proxy, Kali sandbox, PostgreSQL, Neo4jGHCR Docker images + docker compose
The SDK connects to the services via environment variables:
  • DECEPTICON_LLM__PROXY_URL — the LiteLLM proxy (default http://localhost:4000)
  • SAAS_SANDBOX_URL — the sandbox HTTP daemon (e.g. http://localhost:9999)
For a turnkey local stack, use the Quick Start installer. The pip package is for embedding the agents into your own service.

​
Use a pre-built agent

from decepticon.agents.standard.recon import create_recon_agent

agent = create_recon_agent()   # default OSS configuration
Each of the 16 agent factories accepts langchain-style keyword overrides — tools=, middleware=, system_prompt=, llm=, and more.

​
Extend with a plugin bundle

Ship proprietary tools, middleware, prompts, or sub-agents without forking — register a PluginBundle under the decepticon.bundles entry point: 
from decepticon.plugin_loader import PluginBundle

MY_BUNDLE = PluginBundle(
    bundle="mybundle",
    replaced_tools={"ask_user_question": my_ask_tool},
    prompts={"recon": {"prepend": "<MY_HEADER>..."}},
)

# your package's pyproject.toml
[project.entry-points."decepticon.bundles"]
mybundle = "my_pkg.bundles:MY_BUNDLE"
Activate it with DECEPTICON_PLUGINS=standard,mybundle. This is exactly how a downstream product layers proprietary capability on top of the open core — it depends on decepticon, it does not fork it.

​
Versioning

Pin a compatible range in your pyproject.toml: 
dependencies = ["decepticon>=1.1,<2"]
The full override surface — factory kwargs, declarative PluginBundle plugins, build_middleware(slots=...) for custom orchestrators, and the safety gate — is documented in docs/library-usage.md.