Atropos

A standalone rule and workflow engine: test a decision, explicitly authorize a workflow, and track every step through completion or an uncertain outcome.

Atropos 1.0.1 is free software under GPL-3.0-only. It runs on your own infrastructure, independently of Atraxis and without an AI provider. Atraxis can supply its web and terminal interfaces; Atropos owns the rules, permissions, storage and workflow execution.

Website · Engine on PyPI · Client on PyPI · User guide · Contributing · Roadmap

What can you do with it?

• Manage decision rules: create YAML drafts, keep immutable revisions, test concrete scenarios and explicitly activate a tested version. The documented version-1 rule model uses ZEN 2.1.2.
• Run bounded workflows: validate a graph, submit it with a deduplication key, advance it through workers, inspect persisted results and reconcile uncertainty.
• Control who can act: the rule service checks organization, group, resource and operation scopes at admission and again before execution.
• Connect approved executors: use registered actions or an explicitly configured Auton adapter. Optional Alertmanager delivery reports workflow outcomes.
• Operate persistent state: start with SQLite and its integrated queue; choose other documented storage/delivery adapters when needed.

For example, an operator can test a CPU decision rule and then explicitly dispatch an approved diagnostic for the affected target. Saving, testing or activating a rule does not start that diagnostic. Collection, decision and execution remain separate operations.

How the components fit together

Inside Atropos, the engine and local terminal read and write the configured persistent storage. The database cylinder holds rule versions and tests, workflow runs and results, and audit history. SQLite is the default: a local file, with no separate database server required. Other storage adapters are documented in the backend guide. The frame indicates component ownership, not a requirement to run everything in one process, container or host.

The Atropos terminal is the local atropos command for trusted operators: validate, submit, run and inspect workflows. Its built-in actions are registered demo actions. The authenticated rule service and its guarded workers provide scoped rule-driven dispatch. The terminal and service share data only when configured to use the same storage and namespace.

Coloured logos identify optional external software: Atraxis connects through atropos-client and the authenticated API; Auton executes authorized jobs; Alertmanager routes configured notifications. Saving, testing or activating a rule does not automatically launch a workflow.

Prometheus and Covenant are not required to run Atropos. Monit-Docker retains its own monitoring, local actions and protections when used alongside Atropos.

Container installation

Use the Docker guide for the Linux amd64 image, persistent state, TLS placement and the optional worker using the same image.

Start here

The supported reference covers Linux amd64 and Python 3.11/3.12. On Debian/Ubuntu, install the system libmagic1 library and Python's venv support:

sudo apt-get install python3-venv libmagic1
python3 -m venv .venv
. .venv/bin/activate
python -m pip install 'atraxis-atropos==1.0.1'
python -m pip check
atropos --help

The PyPI distribution is named atraxis-atropos; the command and Python module are atropos. The unrelated PyPI package named atropos is not this engine.

Run a harmless first workflow

Create a file in an empty working directory. This single step returns its inputs; it does not contact a service or modify a supervised resource:

cat > hello.yml <<'YAML'
version: 1
name: hello
start: report
steps:
  report:
    action: core.echo
    with:
      message: Hello from Atropos
YAML

export ATROPOS_STORAGE_BACKEND=sqlite
export ATROPOS_STORAGE_URL=sqlite:///atropos.db
atropos validate hello.yml
atropos plan hello.yml
atropos submit hello.yml --target demo-node --dedup-key hello-001
atropos worker --once

Copy the run ID returned by submit, then inspect it with atropos status RUN_ID. For this one-step example, a successful worker completes the run. In a multi-step workflow, worker --once attempts one step per configured worker; use atropos worker for continuous processing. Submission means queued, not completed.

Run the rule service

In a dedicated engine environment, install the service dependencies:

python -m pip install 'atraxis-atropos[service]==1.0.1'

Follow the rule service guide to create the private profile, provision identities and permissions, configure storage and verified HTTPS, then start the loopback listener:

atropos rules-serve --config /private/atropos-service.yml --port 8082

The profile path is an example, not a bundled ready-to-use configuration. Installing the package does not start the service, create credentials or authorize actions.

Install only the API client

In the consuming application's separate environment:

python -m pip install 'atropos-client==1.0.1'

The base client does not install the engine, Redis or ZEN. Add [observations] when that application needs signed observation envelopes. Follow its own dependency pins: Atraxis 1.0.0 still pins client 0.1.0a10, whose functional code matches 1.0.0 apart from the version constant. Do not override that pin inside Atraxis's environment.

Install from source instead

git clone https://github.com/decryptus/atropos.git
cd atropos
git checkout v1.0.1
python -m pip install .

Use a virtual environment and the same system prerequisites. Runnable examples are in examples/; cloning is not needed for the inline PyPI quickstart.

Persistence and failure semantics

SQLite with its integrated queue is the default. Backend configuration also covers PostgreSQL, MySQL/MariaDB, Redis and installed plugins. Storage and delivery roles are configured independently; switching them does not migrate data.

A confirmed failed action can follow its bounded retry policy. An action whose external result is unknown becomes uncertain and keeps its target lock until an authorized operator investigates and resolves it. A timeout does not prove a remote action stopped. There is no exactly-once guarantee for external effects.

The stable support claim is limited to the qualified reference. High availability, hot backup, automatic pruning and sandboxing arbitrary registered code are not included. Use cold backup and restore and plan capacity for retained runs and audit history.

Documentation

For architecture, tests and release engineering, use the separate contributor guide. Planned work is in the roadmap; brand assets are also available.

License

Project-owned code and documentation are licensed under GNU GPL version 3 only (LICENSE, SPDX GPL-3.0-only). Dependencies retain their own licenses.