Aura Workshop v1.3.91 Documentation

Complete reference for Aura Workshop -- a model-agnostic AI agent orchestration platform. From first launch through advanced multi-agent teams, automation workflows, and the full REST API.

First Launch

When you open Aura Workshop for the first time, the app creates a local SQLite database at:

• macOS: ~/Library/Application Support/aura-workshop/aura-workshop.db
• Windows: %APPDATA%\aura-workshop\aura-workshop.db
• Linux: ~/.config/aura-workshop/aura-workshop.db

All settings, conversations, team definitions, workflows, listener configurations, scheduled tasks, credentials, and billing data are stored in this single database file.

On first launch the app also:

• Detects whether Docker is available. If Docker is not installed or not running, the app enables native mode automatically, which runs commands directly on the host system.
• Installs bundled skills (PDF, DOCX, XLSX, PPTX, and various development workflow skills) to the skills directory.
• Initializes the credential encryption system, generating an AES-256-GCM key and storing it in the macOS Keychain or Windows Credential Manager.
• Starts the Web UI server on port 18800 (configurable), serving the full interface via HTTP for browser access.
• Auto-starts any listeners that were previously running.

Prerequisites

Models & Providers (Quick Setup)

To start using Aura Workshop you need at least one LLM provider configured. You can use cloud APIs, local inference, or both.

1. Navigate to the MODELS page using the sidebar navigation.
2. Click a provider card (Anthropic, OpenAI, Google, DeepSeek, etc.) to expand it.
3. Enter your API key in the key field. The key is encrypted with AES-256-GCM before being stored in the database.
4. Select a model from the dropdown or type a custom model ID.
5. Optionally adjust sampling parameters: temperature, top-p, max tokens.
6. The base URL is auto-filled based on the provider preset but can be overridden for custom endpoints.

Each provider stores its API key independently. When you switch between providers, the app loads the previously saved key for that provider.

Local providers (Ollama, Aura AI) do not require an API key. Select one and ensure the corresponding inference server is running locally. See Aura AI and Ollama for setup details.

Quick Model Picker

A model selector in the top-right corner of the app lets you quickly switch between configured providers and models without opening the full MODELS page. Click it to see all available models grouped by provider, and select one to switch immediately. The active model is captured per-task at launch time, so you can switch models between tasks without affecting running ones.

Web UI (Browser Access)

Aura Workshop includes an embedded axum HTTP server that serves the full SolidJS UI via any web browser. This enables headless Linux server deployment and remote access from any device on the network.

Accessing the Web UI

The Web UI server auto-starts on port 18800 by default. Open your browser and navigate to:

http://<machine-ip>:18800

The actual machine IP address is displayed in Settings > Connectivity > Web UI Server.

Configuration

Configure the Web UI server in Settings > Connectivity:

Authentication

When an auth token is configured, all requests to the Web UI must include it:

• As an Authorization: Bearer <token> header
• Or via a login prompt in the browser

How It Works

The browser-based UI uses the same SolidJS frontend with a web transport layer instead of Tauri IPC:

• REST endpoints replace Tauri invoke() calls for all commands
• Server-Sent Events (SSE) replace Tauri event listeners for real-time streaming
• Lazy Tauri imports -- the frontend detects whether it is running inside Tauri or a browser and loads the appropriate transport

All features work identically in browser mode: agent tasks, chat, settings, listeners, webhooks, schedules, skills, MCP servers, and teams.

Headless Server Usage

For headless Linux servers without a desktop environment:

1. Install the .deb or .AppImage package
2. Launch with a virtual display: xvfb-run aura-workshop
3. Access the full UI at http://<server-ip>:18800
4. Configure API keys, models, and all settings through the browser

Unified Task Interface

Aura Workshop uses a single input box for everything. There are no separate "Chat" and "Agent" modes to switch between. Type anything -- a quick question, a complex project brief, or an automation request -- and the system automatically determines the right execution path.

Input Field

The prompt input is at the bottom of the main panel. It reads: "Describe what you want to build..."

Below the input field, a toolbar provides additional controls:

• Attach Files -- attach individual files to the conversation (images, documents, code files)
• Attach Folder -- mount a project folder so the agent knows where to read and write files
• Tools -- toggle which tools are available for the current task
• Voice -- use speech-to-text to dictate your prompt

Category Prompt Cards

When you start a new task, category prompt cards appear above the input field to help you get started quickly:

Clicking a card pre-fills the input with a relevant prompt template that you can customize before sending.

Running Multiple Tasks

Multiple tasks can run simultaneously, each potentially using a different model or provider. Start a new task while another is running -- each gets its own cancel token and event stream. Switch between active tasks in the sidebar to monitor progress. The model active at the time each task was launched is captured and used for that task's duration.

Task Classification

When you send a prompt, Aura's classification system analyzes it and routes to the right execution path automatically:

You don't need to pick a team or workflow manually -- just describe what you want and the system figures out the best approach.

How Classification Works Internally

The classify_task() function sends a one-shot LLM call that analyzes the prompt and returns the classification type, team name (if applicable), workflow type, and role specifications. For NEW tasks, the classifier also generates complete role definitions on the fly. The classification happens at the application level -- no special model cooperation is required.

Mounted Folders

The mount folder button (folder icon next to Send) tells the agent where to work on your filesystem. Always mount a folder when you expect the agent to create or modify files.

How to Use

1. Click the folder icon in the input toolbar.
2. A native file dialog opens. Select one or more directories.
3. Selected folders appear as a "MOUNTED FOLDERS" badge above the input field.
4. When you send a message, the selected paths are passed as the project_path to the agent.
5. In Docker mode, these paths are bind-mounted into the container at /workspace.
6. In native mode, the first path is used as the working directory for bash commands.

When to Mount

Important Notes

• Always mount a folder when you expect file creation or modification -- otherwise the agent may write to a random location or your home directory.
• You can mount multiple folders -- useful when a task needs to reference one project and write to another.
• Paths are per-session -- they reset when you start a new task. You need to re-mount when starting fresh.
• For team tasks, every role in the workflow inherits the same mounted path. All roles read from and write to the same directory.
• Duplicates are automatically filtered out.

Sample Prompts (Validated Test Scenarios)

These prompts have been tested end-to-end and demonstrate Aura's core capabilities.

1. Simple Question (CHAT)

What are the three laws of thermodynamics? One sentence each.

What happens: Classified as CHAT. Conversational response, no tools invoked. Status: completed.

2. Code Generation (SINGLE)

Write a Python function called is_palindrome that checks if a string reads the same forwards and backwards. Save it to palindrome.py

What happens: Single agent writes the code, saves the file, optionally runs tests. You'll see write_file and bash tool calls in the sidebar.

3. Clarification (CLARIFY)

Help me with my project

What happens: The system detects the request is too vague. Instead of guessing, it asks 3-5 specific clarifying questions. Task status shows "Needs Response" in amber. Reply with details and the system re-classifies.

4. Team Workflow -- Software Development (TEAM)

Build a full REST API for a todo list app with CRUD endpoints, database schema, and unit tests

What happens: Routes to the Software Dev Team (5 roles: Product Manager, Architect, Developer, QA Engineer, DevOps). The PM may ask clarifying questions -- the workflow pauses until you answer. The Workflow Progress panel shows each role's status.

5. New Team Creation (NEW)

Design and build a data ingestion pipeline that reads CSV files, validates the data, transforms it, and loads it into PostgreSQL

What happens: No existing team matches, so the classification creates a new pipeline team with custom roles. The team is saved for future reuse.

6. Scheduled Task (SCHEDULE)

Every Monday at 9am, compile a summary of all git commits from the past week and email it to [email protected]

What happens: A schedule is created and appears in the AUTO tab. The agent runs the task immediately as a first execution, then fires automatically at the configured time.

7. Parallel Translation (NEW + Fan-Out)

Translate this product documentation into Spanish, French, and German simultaneously, then have each reviewed by a native speaker

What happens: Creates a Localization Team with parallel workflow -- translators run simultaneously, then reviewers check each language. The Workflow Progress panel shows parallel nodes running at the same time.

How Orchestration Works

Aura Workshop has a built-in AI orchestration engine. Instead of doing everything as a single agent, the system can automatically route complex tasks to multi-agent teams, create automation workflows, set up scheduled tasks, and wire triggers -- all from natural language prompts.

Routing Logic

Agent Loop

The agent operates in a loop of up to 50 turns (configurable). Each turn:

1. Sends the conversation history and available tools to the LLM.
2. Receives a response that may contain text and/or tool calls.
3. Executes any tool calls (file reads, writes, bash commands, etc.).
4. Feeds tool results back to the LLM for the next turn.

The loop ends when the LLM responds with only text (no tool calls), or the maximum turn count is reached.

Multi-Agent Teams

Teams define multiple AI roles that work together. Each role runs as a separate agent with its own system prompt, and the workflow engine manages execution order, parallel processing, and data passing between roles.

Default Teams

Software Dev Team (5 roles, fan-out enabled):

• Product Manager → Architect → Developer (fan-out) → QA Engineer → DevOps
• The Developer role uses fan-out: the Architect produces a task list, and one developer agent spawns per task in parallel

Content Writing Team (3 roles, sequential):

• Research Lead → Writer → Editor

Using Teams

Automatic -- just describe what you need. Complex tasks auto-route to the matching team:

Manual via Settings -- create or edit teams in Settings > Teams with the visual workflow editor.

Via natural language -- ask the agent to create a team:

Creating and Editing Teams

1. Open Settings > Teams and click Create Team.
2. Add roles -- each role needs a name and a system prompt.
3. Choose a workflow type: Sequential or Pipeline (with validation gates).
4. Use the Workflow Editor to customize: add Script, Webhook, Validate, or Approval Gate steps between roles.
5. Enable Fan-Out on any role by double-clicking the node and checking "Enable Fan-Out".
6. Import/Export -- click Import to load a team JSON, or Export on any team to download it.

Workflow Progress Panel

When a team runs, the right panel shows:

• All roles with status icons (pending, running, completed, failed)
• Fan-out sub-agents shown as indented items under the parent role
• Click any role to view only that role's output in the main panel
• Click "Show All" to return to the combined view
• Progress bar with completion count

Role Library (20 Built-in Roles)

Aura Workshop ships with 20 built-in roles organized into 6 categories, providing ready-to-use specialist agents for common tasks. You can also create unlimited custom roles.

Built-in Role Categories

Each built-in role includes a curated system prompt with domain-specific instructions, tool preferences, and output format guidelines.

Managing Roles in Settings

Open Settings → Roles to manage all roles:

• List all roles -- built-in and custom roles displayed by category
• Create -- click "Create Role" and provide a name, category, and system prompt
• Edit -- modify any role's name, system prompt, and tool access
• Duplicate -- clone an existing role as a starting point for a new one
• Delete -- remove custom roles (built-in roles cannot be deleted)

Tool Checkboxes

Each role has checkboxes controlling which tools it can access. Default tools include read_file, list_dir, glob, grep, and role_complete. You can enable or disable individual tools per role to enforce constraints (for example, giving a Research Lead read-only access by disabling write_file and bash).

Custom Roles

Custom roles are saved to ~/.aura/roles/ as .md files with YAML frontmatter containing the role name, category, description, and tool list. These files can be version-controlled, shared between machines, or manually edited.

Auto-Created Roles

When the task classifier creates a new team (classification type NEW), it generates role definitions on the fly. These auto-created roles are saved to the Role Library automatically so they can be reused in future teams.

Structured Handoff

When agents in a team workflow complete their role, they pass structured handoff data to downstream agents using the role_complete tool. This ensures critical context is not lost between workflow steps.

Handoff Data Structure

Each handoff includes four structured fields:

• Summary -- A concise description of what the role accomplished and the current state of the deliverable.
• Files -- A list of file paths that were created or modified, so the next role knows exactly where to look.
• Decisions -- Key decisions made during execution (e.g., "chose PostgreSQL over MySQL", "used REST instead of GraphQL") that downstream roles should respect.
• Constraints -- Limitations or requirements discovered during execution that downstream roles must adhere to (e.g., "API rate limit is 100 req/min", "must support Python 3.9+").

How It Works

When a role finishes, the agent calls role_complete with the handoff payload. The workflow engine:

1. Saves the handoff data to the task record.
2. Injects the handoff into the system prompt of the next role in the workflow.
3. Marks the upstream role node as completed in the Workflow Progress panel.

Fan-Out (Parallel Agents)

Fan-Out lets a role automatically spawn multiple agents in parallel -- one per item from an upstream role's output list.

How to enable: Double-click a role node in the Workflow Editor → check "Enable Fan-Out" → set Source Node and Max Parallel Agents.

How it works: The source role produces a numbered list. The fan-out executor detects the list, splits it, and spawns one agent per item. Results are merged for the next role.

Role Guardrails

Every agent in a team workflow automatically receives system-enforced rules:

• First role (entry node): CAN ask clarifying questions, but must ask ONLY questions and stop -- no deliverable alongside questions
• Middle/downstream roles: Cannot ask questions -- must work with what the previous role provided
• All roles: Cannot do other roles' jobs, must stop after delivering their files, cannot loop or re-check their own work

These guardrails are injected at the executor level and apply to every team, including user-created ones. They prevent agents from overstepping their responsibilities and ensure the workflow progresses cleanly.

Workflow Pause & Resume

When the first agent in a team workflow (typically the PM) asks clarifying questions, the workflow pauses automatically:

1. The PM asks questions (e.g., "What database do you prefer?")
2. Task status changes to "Needs Response"
3. You type your answer in the input box
4. The workflow resumes from where it paused, feeding your answer to the next agents

This ensures you get exactly the product you want instead of the agent guessing.

Cross-Session Memory

Aura Workshop maintains persistent memory files that survive across sessions, allowing the agent to recall user preferences, project context, and prior feedback without being told again.

Memory Storage

Memory files are stored as markdown in two locations:

• User-level: ~/.aura/memory/ -- global preferences and feedback that apply everywhere
• Project-level: .aura/memory/ (inside project root) -- project-specific architecture, conventions, and decisions

Auto-Extraction

After a task completes, the agent automatically analyzes the conversation for memorable information. If it detects user preferences, corrections, or important project context, it writes a new memory file (or updates an existing one) without being asked. A memory index file (MEMORY.md) is maintained with a summary of all stored memories.

System Prompt Injection

At the start of every agent session, all memory files are read and injected into the system prompt. This means the agent "remembers" everything it has learned across previous sessions. Memories survive context compaction -- they are re-injected even after the conversation is compressed.

Context Compression

Long-running agent sessions can exceed the model's context window. Aura Workshop automatically compresses the conversation to stay within limits while preserving critical information.

How Compaction Works

1. Threshold detection -- Before each API call, the system estimates the current context size. When it reaches 80% of the model's context window, compaction triggers automatically.
2. LLM summarization -- The conversation history is sent to the model with a summarization prompt. The model produces a compressed summary that preserves key decisions, file paths, tool results, and task state.
3. Context replacement -- The compressed summary replaces the full conversation history. Only the summary and the most recent messages are kept.

Truncation Fallback

If the LLM summarization call itself fails (e.g., the context is already too large to summarize), the system falls back to a simple truncation strategy: it keeps the system prompt, the most recent N messages, and drops the oldest messages.

Circuit Breaker

If compaction fails 3 times in a row, the circuit breaker activates and stops attempting further compaction for the remainder of the session. This prevents infinite retry loops.

Parallel Task Execution

Aura Workshop supports running multiple agent tasks simultaneously, each potentially using a different model or provider.

• Per-task cancel tokens -- Each running task gets its own AtomicBool cancel token, keyed by task_id. Stopping one task does not affect others.
• Event routing -- All streaming events (text, tool calls, workflow progress) are tagged with their task_id. The frontend routes events to the correct task panel.
• Independent model selection -- Each task uses whatever model and provider were configured at the time it was launched.

You can stop tasks individually (click the stop button on a specific task) or stop all running tasks at once.

Crash-Safe Transcripts

Aura Workshop persists the full agent transcript to the database before every API call. If the app crashes, the machine loses power, or the process is killed, the conversation is recoverable up to the last completed turn.

1. Before each LLM API call, the current conversation history (including all tool calls and results so far) is written to the task_messages table in the SQLite database.
2. When you relaunch the app, interrupted tasks appear in the sidebar with a "Resume" indicator.
3. Clicking Resume reloads the persisted transcript and continues the agent loop from where it left off.

You never lose work due to unexpected shutdowns. The agent picks up exactly where it stopped, with full context.

Schedules & Listeners

The AUTO tab manages all automation triggers.

Schedules (Cron-Based)

Schedules run tasks at recurring intervals using cron expressions.

• Create from the AUTO tab or let the agent create one from natural language
• Supports standard cron syntax: 0 9 * * MON (every Monday at 9am)
• Each schedule can trigger a regular agent task, a team workflow, or an automation workflow
• Convention: set prompt to [team:TEAM_ID] Your message here for teams, or [workflow:WORKFLOW_ID] for workflows
• Enable/disable without deleting

Listeners (Event-Driven)

Listeners watch for incoming messages from external platforms and trigger agent responses.

• WebChat -- WebSocket server for the Chrome Extension and embeddable chat widget
• WhatsApp -- WhatsApp Business API listener (requires authentication setup)
• Telegram -- Telegram Bot API listener
• Slack -- Slack workspace listener

Each listener can optionally enable "Agent Tools" for full tool access, or run in chat-only mode.

Automation Workflows

Automation workflows are pipelines that orchestrate triggers, conditions, scripts, webhooks, and teams. Unlike teams (which are multi-agent role-based), workflows handle the plumbing: when to run, what data to route, which conditions to check.

Creating Workflows

Via natural language -- describe the automation you need:

Via Settings -- go to Settings > Workflows > Create Workflow. Use the visual editor to add nodes, connect them, and configure each one.

Via Import -- click Import on the Workflows tab to load a workflow JSON file.

Node Types

Conditional Expressions

The conditional node evaluates expressions against workflow data:

• node_id.field == "value" -- equality
• node_id.field != "value" -- inequality
• node_id.field > 100 -- numeric comparison
• node_id.field contains "text" -- substring check
• node_id.field exists -- field is not null
• node_id.field is_empty -- field is null or empty

Workflow Templates

Pre-built templates are available for common use cases:

Import any template via Settings > Workflows > Import.

Cloud Providers

Aura Workshop supports 9 cloud LLM providers out of the box. Each is represented as an expandable card on the MODELS page.

Provider Card Details

Click any provider card to expand it and configure:

• API Key -- encrypted with AES-256-GCM before storage. Each provider stores its key independently.
• Model Selector -- dropdown populated with provider-specific models. You can also type a custom model ID.
• Sampling Parameters -- sliders for temperature, top-p, top-k, min-p, repeat penalty, and max tokens. Not all parameters are supported by every provider; unsupported ones are silently ignored.
• Base URL -- auto-filled from the provider preset. Override for proxies or custom deployments.

Aura AI (Local GGUF Inference)

Aura AI is a built-in inference engine bundled with Aura Workshop. It runs GGUF models locally without requiring any external software.

How It Works

The aura-inference binary (Go-based, ~31MB) is bundled as a Tauri sidecar. It provides an OpenAI-compatible API on localhost for serving quantized GGUF models.

Model Discovery

Click Scan Models to discover GGUF files in:

• ~/.cache/huggingface/hub/ -- models downloaded via the HuggingFace Downloader or huggingface-cli
• ~/.cache/aura-inference/models/ -- Aura's dedicated model directory

Discovered models appear in a selectable list with file size and quantization level.

Configuration

Launching the Server

1. Select a GGUF model from the scanned list.
2. Configure inference parameters.
3. Click Launch Server.
4. The app auto-configures the provider to aura-ai, sets the base URL to localhost, and selects the model.
5. The server process is managed by the app and automatically killed when the window closes.

Zero API cost -- runs entirely on your hardware.

Ollama

Ollama is auto-detected when running on the local machine. The Ollama card shows all locally available models and lets you pull new ones directly from the Ollama registry. No API key required.

Setup

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model
ollama pull llama3.1

# Ollama runs automatically on localhost:11434
# Aura Workshop auto-detects it

Configuration

Ollama models run entirely locally with zero API costs. They serve as the final fallback in the provider fallback chain when all cloud provider spend limits are reached.

HuggingFace Downloader

The MODELS page includes a HuggingFace model downloader with:

• Curated models -- a selection of recommended unsloth GGUF models optimized for different hardware configurations
• Custom download -- enter any HuggingFace model URL to download it directly
• Download progress -- real-time progress bar with speed and ETA

Downloaded models appear automatically in the Aura AI model scanner and can be launched immediately.

Custom Providers

The Custom Provider Manager lets you save and quickly switch between custom LLM provider configurations.

Adding a Custom Provider

1. Open Settings and navigate to the provider configuration area.
2. Click Add Custom Provider.
3. Fill in the configuration:
   • Name -- A display name for this provider (e.g., "My vLLM Server").
   • Base URL -- The endpoint URL (e.g., http://192.168.1.100:8000/v1).
   • Model ID -- The model identifier the server expects.
   • API Key -- Optional, depending on the server's auth requirements.
4. Save the configuration.

Saved custom providers appear in the model selector dropdown alongside built-in providers. Supports any OpenAI-compatible endpoint: vLLM, TGI, SGLang, LocalAI, LiteLLM, and more.

Agent Tools

Agents have access to a comprehensive set of tools for interacting with the filesystem, executing commands, and managing platform resources.

Core Tools (Native Mode)

Docker Tools

Available when Docker is installed and Docker mode is enabled:

Device Tools (Opt-in via Settings)

Platform Tools (53 tools)

The agent has full CRUD operations for all platform resources:

Security Notes

• platform_get_settings never returns API keys -- only model, provider, base URL, and non-sensitive configuration.
• platform_get_credential returns decrypted values to the agent's internal context but never displays them in chat.
• platform_store_credential encrypts values with AES-256-GCM before writing to the database.

Skills System

Skills are structured instruction sets that guide the agent when performing specific types of tasks.

How Skills Work

1. Skills are stored in the skills directory: ~/Library/Application Support/aura-workshop/skills/ (macOS) or %APPDATA%\aura-workshop\skills\ (Windows).
2. Each skill is a folder containing a SKILL.md file with YAML frontmatter (name, description) and markdown instructions.
3. When the agent starts, all available skills are listed in the system prompt.
4. When a user request matches a skill, the agent reads the skill's SKILL.md file and follows its instructions.

Bundled Skills

Document and creative skills:

• pdf, docx, xlsx, pptx -- Office document processing
• algorithmic-art, canvas-design, frontend-design -- Visual design
• brand-guidelines, internal-comms, doc-coauthoring -- Business documents
• mcp-builder, skill-creator, slack-gif-creator -- Developer tools
• theme-factory, web-artifacts-builder, webapp-testing -- Web development

Development workflow skills (superpowers):

• brainstorming, writing-plans, executing-plans
• test-driven-development, systematic-debugging
• requesting-code-review, receiving-code-review
• finishing-a-development-branch, using-git-worktrees
• dispatching-parallel-agents, subagent-driven-development
• verification-before-completion, using-superpowers, writing-skills

Platform integration:

• credential-store -- teaches the agent to detect, store, and retrieve credentials securely

Adding Custom Skills

1. Click "+ Add Skill" in the Skills panel to import a skill folder from your computer.
2. Alternatively, create a folder in the skills directory with a SKILL.md file.
3. The SKILL.md must have YAML frontmatter with name and description fields.

Each skill in Settings > Skills has an Edit button for modifying the SKILL.md content. Changes take effect on the next agent task.

MCP Servers

The Model Context Protocol (MCP) allows Aura Workshop to connect to external tool servers, extending the agent's capabilities beyond built-in tools.

Adding an MCP Server

1. Open Settings > MCPs.
2. Click Add Server.
3. Choose a transport type:
   • HTTP: provide the server URL (e.g., http://localhost:3000/mcp).
   • stdio: provide the command and arguments to spawn the server process (e.g., command npx, args @playwright/mcp).
4. Optionally configure OAuth credentials if the server requires authentication.
5. Toggle the server to enabled.
6. The app connects and discovers available tools. These tools appear in the /tools listing with an mcp_ prefix.

Playwright Browser Automation

Add an MCP server with transport stdio, command npx, args @playwright/mcp. The agent can then browse the web, interact with pages, take screenshots, and extract content. MCP tool results are truncated to 8000 characters to prevent context overflow.

Browser-Use MCP (Bundled)

Browser-Use is bundled as a backup browser automation MCP server alongside Playwright. It is auto-connected on startup with no setup required. The Python virtual environment and all dependencies are bundled with the installer.

Custom MCP Servers

Any server implementing the MCP protocol can be added. Tool names are formatted as mcp_{server_id}_{tool_name} with hyphens and colons replaced by underscores.

Settings: General

The General tab controls core execution and interaction preferences.

• Native Mode -- toggle between native execution (commands run directly on the host via sh -c or cmd /C) and Docker execution (commands run in isolated containers). Native mode is the default when Docker is not installed.
• Sampling Parameters -- temperature, top-p, top-k, min-p, repeat penalty, max tokens. These are the global defaults applied to all new tasks. Not all parameters are supported by every provider; unsupported ones are silently ignored.
• Thinking Level -- controls the reasoning depth of models that support extended thinking (off, low, medium, high).
• Elevated Bash -- when enabled, bash commands run with elevated privileges (sudo on macOS/Linux, administrator on Windows).
• Device Tools -- opt-in toggles for screen capture, camera capture, and system notifications.
• Voice/TTS -- voice input configuration and text-to-speech output settings.

Settings: Security & License

• Biometric Authentication -- toggle Touch ID (macOS) or Windows Hello (Windows). When enabled, biometric auth is required to access the Credentials and Cloud Storage settings tabs. Once authenticated, access is granted for the remainder of the session.
• License Key -- enter and activate your license key. License tiers (Community, Pro, Business, Enterprise) gate access to certain features like the visual workflow editor. License validation is cached locally and periodically re-verified.

Settings: Billing & Spend Tracking

Complete cost management for all LLM API usage.

Usage Dashboard

• Usage Summary -- table showing today/month/all-time cost per provider with token counts
• Expenses Chart -- full-width bar chart of daily spend
• Per-Model Charts -- for each model used: API requests area chart and tokens area chart
• Reset Usage button to clear all tracking data

Spend Limits

Set daily and monthly spending caps per configured provider. When a provider hits its limit, Aura automatically switches to the next available provider in your fallback list.

Provider Fallback Order

Configure a priority-ordered list of backup providers. When the primary provider hits its spend limit, Aura switches mid-session with a notification. Local models (Aura AI, Ollama) serve as zero-cost final fallbacks.

Model Pricing

Editable pricing table with input/output cost per million tokens for every model. Keep these updated with your provider's current rates for accurate cost tracking.

How Token Tracking Works

• Cloud APIs with exact counts: Anthropic and non-streaming responses include token usage in the API response
• Streaming APIs (estimated): DeepSeek, OpenAI streaming, and other SSE-based APIs don't return exact token counts. Aura estimates from text length (~3.5 characters per token)
• All estimates are slightly conservative (over-count rather than under-count)

Settings: Connectivity (Web Server)

Configure the embedded Web UI server for browser-based access.

The machine's IP address is displayed here for easy reference when connecting from other devices.

Settings: Skills

• Lists all installed skills with their name, description, and file path
• Edit -- opens a modal editor for the skill's SKILL.md content (YAML frontmatter + markdown instructions)
• Delete -- removes the skill folder
• + Add Skill -- import a skill folder from your computer or create from scratch

Settings: MCPs

• Lists all MCP server connections with status indicators (connected/disconnected)
• Add Server -- configure HTTP or stdio transport, optional OAuth credentials
• Enable/Disable -- toggle individual servers without removing them
• View discovered tools for each connected server

Settings: Data Management

Database and data management operations:

Settings: Teams

• Lists all teams (built-in and user-created) with role count and workflow type
• Create Team -- opens the team builder with a visual role picker
• Edit -- modify team roles, workflow type, fan-out settings, and role prompts
• Import/Export -- share teams as JSON files between installations
• The role picker lets you browse all available roles by category, preview system prompts, and add roles with one click

Settings: Roles

• Displays all 20 built-in roles across 6 categories plus any custom roles
• Create Role -- name, category, system prompt, and tool checkboxes
• Edit -- modify the role's system prompt and tool access
• Duplicate -- clone an existing role as a starting point
• Delete -- remove custom roles (built-in roles are protected)
• Tool checkboxes with defaults: read_file, list_dir, glob, grep, role_complete
• Custom roles are saved to ~/.aura/roles/ as .md files with YAML frontmatter

Settings: Workflows (Enterprise)

The visual workflow editor provides a node-based canvas with drag-and-drop for creating automation pipelines. This feature is available on Enterprise and Business license tiers.

• Create workflows with any combination of the 11 node types
• Connect nodes with edges to define execution flow
• Configure each node's parameters by double-clicking
• Test workflows with sample data before deploying
• Import/Export workflows as JSON

Settings: Credentials

Encrypted credential store for sensitive data used by agents during task execution.

• All values encrypted with AES-256-GCM before writing to the database
• Encryption key stored in the system keychain (macOS Keychain, Windows Credential Manager)
• Access requires biometric authentication (Touch ID / Windows Hello)
• Store API keys, tokens, passwords, connection strings, and other secrets
• Agents access credentials via the credential-store skill -- values enter the agent's internal context but are never displayed in chat

Settings: Cloud Storage

Connect to cloud storage providers so agents can read from and write to your cloud files.

Supported Providers

• Amazon S3 -- bucket access via access key + secret
• Google Cloud Storage (GCS) -- bucket access via service account or OAuth
• Azure Blob Storage -- container access via connection string
• Dropbox -- OAuth2 authorization flow
• Box -- OAuth2 authorization flow
• OneDrive -- OAuth2 authorization flow
• Google Drive -- OAuth2 authorization flow

For OAuth providers, a local callback server on port 18793 handles the authorization flow. Access to cloud storage is gated behind biometric authentication.

Settings: Updates

• Check for Updates -- queries the release server for the latest version
• Release Notes -- view what changed in the available update
• Download -- download the update package with progress indicator
• Install -- apply the update and restart the app

The current version (v1.3.91) is displayed at the top of the Updates tab.

Chrome Extension

The Aura Workshop Chrome Extension brings your AI agent into any browser tab. Chat with your agent, ask about the page you're viewing, summarize content, or use selected text -- all from a side panel.

Prerequisites

• Aura Workshop desktop app installed and running
• A WebChat listener created and started (Settings > AUTO > + > WebChat)
• The WebChat listener's "Agent Tools" toggle set to your preference (on = full agent, off = chat only)

Installation

1. Download aura-workshop-chrome-extension.zip from the release page
2. Unzip the file to a permanent location
3. Open Chrome and navigate to chrome://extensions
4. Enable Developer mode
5. Click Load unpacked and select the unzipped folder

Usage

Click the extension icon to open the side panel. It connects via WebSocket on the WebChat listener port (default 18792).

Keyboard shortcut: Ctrl+Shift+Y (Windows/Linux) or Cmd+Shift+Y (macOS)

Quick Actions

Each browser tab maintains its own conversation context. File attachments via drag-and-drop and screenshot paste are supported.

Privacy

The extension communicates only with your local Aura Workshop instance (localhost:18792). No data is sent to external servers by the extension itself. Page content is only extracted when you click a quick action button.

Embeddable Chat Widget

Aura Workshop provides an embeddable chat widget that you can add to any website, enabling visitors to interact with your configured agent directly from a web page.

Setup

1. Create a new Listener with the platform type set to WebChat.
2. Start the listener. It launches a WebSocket server.
3. Copy the provided JavaScript snippet from the listener configuration panel.
4. Paste the snippet into your website's HTML.

Features

• WebSocket-based -- real-time, bidirectional communication
• Configurable appearance -- customize colors, position, title text to match your website
• Agent tools support -- optionally use the full agent toolset, controlled by the "Agent Tools" toggle

The JavaScript snippet creates a floating chat button on your page. When clicked, it opens a chat panel that connects to your running Aura Workshop instance.

Cloud Storage Integration

Once a cloud storage provider is connected (see Settings: Cloud Storage), agents can read files from and write files to that storage during tasks.

Example prompts:

• "Download the quarterly report from my Google Drive and summarize it"
• "Upload this PDF to my Dropbox"
• "Read the CSV files from our S3 bucket and analyze the data"

REST API Overview

Aura Workshop includes an embedded HTTP server (default port 18800) that exposes the full platform as a REST API. Every feature available in the desktop app is also available via HTTP. All endpoints are prefixed with /api.

Authentication

When a token is configured, include it as a Bearer token:

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:18800/api/tasks

If no token is configured, all API requests are allowed without authentication (suitable for local-only access).

Tasks

Conversations (Chat)

Teams

Automation Workflows

Schedules

Listeners

Webhooks

Billing & Usage

Settings & Data Management

Streaming (Server-Sent Events)

Several endpoints return SSE streams for real-time updates. Connect with EventSource or curl -N.

SSE Event Types:

{"type":"text","content":"Hello world..."}            // Streaming text
{"type":"tool_start","tool":"write_file","input":{}}   // Tool execution started
{"type":"tool_end","tool":"write_file","success":true}  // Tool completed
{"type":"node_running","node_id":"role_0","label":"PM"} // Workflow node status
{"type":"done","total_turns":5}                         // Task completed
{"type":"error","message":"..."}                        // Task failed

Example: Create and Run a Task

# Create task
curl -X POST http://localhost:18800/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"title":"Build API","description":"Build a REST API","prompt":"Build a REST API"}'

# Run it (returns SSE stream)
curl -N -X POST http://localhost:18800/api/tasks/{task_id}/run \
  -H "Content-Type: application/json" \
  -d '{"task_id":"...","message":"Build a REST API for a todo app","project_path":"/path/to/folder"}'