Web App

Attractor is an AI project orchestration system. You define your workflow as a DOT graph — a directed graph where each node is an LLM-powered stage — and Attractor executes it, handling retries, failure diagnosis, and real-time progress monitoring.

Start the server:

# Via Makefile
make run

# Via JAR directly
java -jar attractor-server-*.jar --web-port 7070

Open the UI: http://localhost:7070

The top navigation bar has five views:

There are three ways to create a project:

1. Type a description in the natural language input (e.g., “Build a Go application and run its tests”)
2. Click Generate — the LLM produces a DOT graph
3. Review the graph in the preview pane (toggle between Source and Graph views)
4. Optionally click Iterate to refine the project via LLM
5. Click Create

Paste or type a valid DOT graph into the editor in the Create view, then click Create.

Click 📂 Upload .dot in the Generated DOT section to open a file picker. Select a .dot file from disk — the DOT source loads into the editor, the NL prompt is cleared, and the graph renders automatically. Click Create to execute it. The original filename is preserved and used for artifact labelling.

Click a project tab in the Monitor view to open its detail panel:

• Stage list — each stage shown with status badge, duration, and a log icon
• Log panel — scrollable live log of project events and LLM output
• Graph panel — rendered SVG of the DOT graph with stage status colors overlaid

Clicking Iterate on a completed or failed project opens the Create view pre-filled with the project’s DOT source. When you submit, a new project is created in the same family — sharing the same familyId. Use the << and >> arrows in the project panel header to navigate between family members.

Click Export on any finished project to download a ZIP archive containing both the project metadata and everything the project produced during its run. You can import this ZIP on another Attractor instance to fully restore the project — no re-run needed.

The artifacts/ directory inside the ZIP mirrors the project’s on-disk workspace:

One {nodeId}/ directory is created per stage. The workspace/ directory is shared across all stages, so files written in an early stage are visible to later ones.

Note: artifacts/workspace/ is where you’ll find the actual deliverables — code, compiled binaries, test results, or any other files the LLM was instructed to produce. Stage directories (artifacts/{nodeId}/) contain the paper trail of how each stage was executed.

You can browse individual files directly in the UI without exporting. Click the log icon next to any stage in the stage list to open the artifact browser for that stage, or use the REST API (GET /api/v1/projects/{id}/artifacts) to list and fetch individual files programmatically.

When a stage fails, Attractor automatically asks the LLM to diagnose the failure and generates a failure_report.json in the project’s artifact directory. Click View Failure Report to see the structured diagnosis. The report is also included in the artifacts ZIP download.

• Export — downloads a ZIP containing project-meta.json (all project fields) plus the full artifacts/ directory (workspace, stage logs, prompts, responses). Use this to back up a project or move it to another Attractor instance.
• Import — upload an exported ZIP via the Import view in the nav. The project is restored immediately with its original status and artifacts — no re-run is triggered. If the same project (matched by familyId) already exists, the import is skipped by default.

Note: Old export ZIPs that contain only project-meta.json without an artifacts/ directory are still importable — missing fields default gracefully and the project is restored as metadata-only.

Attractor stores project run history in a database. By default it uses a local SQLite file (attractor.db). Set ATTRACTOR_DB_* environment variables at startup to switch to MySQL or PostgreSQL.

The active backend is shown in the startup log: [attractor] Database: SQLite (attractor.db)

Set ATTRACTOR_DB_URL to a JDBC URL. Simplified URLs without the jdbc: prefix are also accepted:

# PostgreSQL (JDBC form)
export ATTRACTOR_DB_URL="jdbc:postgresql://localhost:5432/attractor?user=app&password=secret"
# PostgreSQL (simplified)
export ATTRACTOR_DB_URL="postgres://app:secret@localhost:5432/attractor"

# MySQL (JDBC form)
export ATTRACTOR_DB_URL="jdbc:mysql://localhost:3306/attractor?user=app&password=secret"
# MySQL (simplified)
export ATTRACTOR_DB_URL="mysql://app:secret@localhost:3306/attractor"

Security: Use environment variables for credentials, not command-line arguments. The startup log always shows a credential-free display name. Use ATTRACTOR_DB_PARAMS=sslmode=require for encrypted connections in production.

Attractor creates the database schema automatically on first start. A misconfigured ATTRACTOR_DB_TYPE causes a clear startup error and clean exit.

Direct API (default) — Attractor makes HTTP calls directly to provider REST APIs. Requires the corresponding API key environment variable to be set before startup.

CLI subprocess — Attractor shells out to installed CLI tools. No environment-variable API keys are needed; authentication is handled by the tool itself.

Custom provider tip: For Ollama, set host to http://localhost, port to 11434, leave API key blank, and set model to the name of a pulled model (e.g. llama3.2). The endpoint must be running before Attractor attempts to reach it.

In CLI mode, each provider has an editable command template. Use {prompt} as the substitution placeholder for the generated prompt text.

The System Tools grid shows detected binaries on the host. Required tools (java, git, dot) must be present for core features to work — a warning banner appears at the top of every page if any are missing. Optional tools are used by LLM-generated project stages and do not block Attractor itself.

Install all required runtime tools with: make install-runtime-deps