Web App

Getting Started

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

Navigation

The top navigation bar has five views:

Creating a Project

There are three ways to create a project:

Option A — Generate from natural language

1. Type a description in the natural language input (e.g., “Build a Go application and run its tests”)
2. Select an Agent from the dropdown next to the Generate button — or leave it on Auto
3. Click Generate — the LLM produces a DOT graph
4. Review the graph in the preview pane (toggle between Source and Graph views)
5. Optionally click Iterate to refine the project via LLM
6. Click Create

The selected Agent and Model are used for both DOT generation and project execution.

Agent and Model selection

The Agent dropdown always includes an Auto option. When Auto is selected, Attractor immediately picks a random enabled agent and model and displays the resolved choice inline next to the dropdown (e.g., → Claude — claude-opus-4-5). You can re-select Auto at any time to re-randomize, or pick a specific agent to override.

Direct API mode

When a specific agent is selected, a Model dropdown appears showing all models fetched from that provider’s API. Selecting a model pins it for both generation and execution. Leaving it on the default uses the provider’s recommended model. The resolved agent and model are remembered per provider across browser sessions.

CLI Subprocess mode

No Model dropdown is shown. The model is controlled entirely by the CLI tool’s own configuration — the label “Tool default” indicates this. To change the model used, configure it via the CLI tool’s own settings (environment variable, config file, or flags). You can optionally add --model {model} to the command template in Settings if you want Attractor to pass a specific model ID to the tool.

Option B — Write DOT directly

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

Option C — Upload a .dot file

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.

Project States

Monitoring a Project

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

Action buttons

Git History Panel

Every project detail tab includes a collapsible Git History bar, located between the project description and the Stages card. It shows the workspace git history for the project — a commit is recorded automatically after each terminal-state event (completed, failed, cancelled, paused).

Collapsed view

The bar shows at a glance:

⎇ main  •  4 commits  •  last: "Run run-001 completed: 3 stages" (2 min ago)

Click the bar (or the ▶ chevron) to expand it into a commit log table.

Expanded view

The expanded panel shows a table of the most recent commits: short hash, subject line, and time-ago. Click the bar again to collapse it.

Degraded states

Refresh

• Auto-refresh — the panel updates automatically 500ms after the project reaches a terminal state (completed/failed/cancelled/paused)
• Manual refresh — click the ↻ button in the bar header to fetch the latest git state on demand

Requirement: The git binary must be available on the server’s PATH. Check Settings → System Tools to confirm it is detected.

Project Versions (Iterate)

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.

Export ZIP Contents

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.

Top-level files

artifacts/ directory

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.

Artifact browser

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.

Failure Diagnosis

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.

Import / Export

• 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.

Database Configuration

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)

Connection string (ATTRACTOR_DB_URL)

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"

Individual parameters

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.

Settings

The Settings page is organised into four cards: Theme, Agents, System Tools, and Info.

Theme

Toggle between dark and light appearance.

Agents

Execution Mode

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.

Providers

Provider toggles are independent per execution mode — enabling a provider in Direct API mode does not enable it in CLI Subprocess mode, and vice versa.

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.

Model list (Direct API)

When a provider is enabled in Direct API mode, its available models are shown inline below the provider toggle. Models are fetched live from the provider’s API and cached in the database.

• Auto-fetch — models are fetched automatically when you first enable a provider.
• Refresh — click the Refresh button to pull the current model list from the provider’s API at any time.
• Fallback — if no models have been fetched yet, Attractor shows a built-in list of well-known models.

The model list drives the Model dropdown on the Create and Iterate pages.

Model selection (CLI Subprocess)

In CLI Subprocess mode no Model dropdown is shown on the Create and Iterate pages — the label reads Tool default. The actual model is determined entirely by the CLI tool’s own configuration:

To have Attractor pass a specific model ID to the CLI tool, add --model {model} to the command template in Settings. The {model} token is substituted with the model ID at call time.

CLI command templates

Each CLI provider has an editable command template. Supported substitution tokens:

Default templates:

Direct API — Advanced Options

These environment variables override the default API endpoints. Useful for proxies, private deployments, or Azure-compatible endpoints.

Custom Provider Bootstrap

These environment variables seed the Custom provider’s Settings UI on first start. Values saved through the Settings UI take precedence on subsequent starts.

System Tools

The System Tools grid shows detected binaries on the host. Required tools (java, git, graphviz) 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

Debug Mode

Set ATTRACTOR_DEBUG to any non-empty value to enable verbose logging and full stack traces in error output.

ATTRACTOR_DEBUG=1 make run