CLI & Reference

Aura Workshop ships a small set of command-line entry points — the headless aura-daemon server and a few native helper sidecars — plus the fixed conventions everything else depends on: network ports, on-disk data locations, the SQLite schema, and license tiers. This page is the quick-reference index for Aura Workshop 1.36.2, closing with a troubleshooting and FAQ section.

aura-daemon CLI

The headless server binary. It is bundled with the desktop app as a sidecar and shipped as the ENTRYPOINT of the Docker daemon image (coolkoo/aura-workshop:daemon-latest). The desktop app itself is launched from the OS launcher and parses no CLI flags — its embedded web server is configured through in-app settings.

Flags

Only two flags are parsed:

aura-daemon [OPTIONS]

OPTIONS:
  --port <PORT>     Override the web server port (default: settings.web_server_port, else 18800)
  --mode <MODE>     full (default) | worker

The daemon runs a single full mode. worker is a backward-compatible alias of full; any other --mode value (including the retired inference-master / inference-worker) prints a notice and falls back to full. The resolved mode is exported as AURA_DAEMON_MODE for the health endpoint.

What full mode starts

• Web server (always) on the resolved port — serves the REST API, SSE, WebSockets, and either the full frontend or the viewer SPA.
• Deployed scheduler loop every 60 s for tasks with background_deploy = 1, plus autonomous [loop:] re-wakes.
• MCP auto-connect for enabled servers (30 s timeout each).
• Deployed listeners auto-start; the webhook server (port 18790) starts only when at least one webhook is deployed.
• Workflow engine — retry poller, resume listener, and startup recovery of running/waiting runs.
• ACP discovery (UDP 18802 listener + broadcast), license validate with a 24 h re-check, and a heartbeat push every 30 s if AURA_HEARTBEAT_URL is set.
• Docker auto-detect — if Docker isn't available the daemon flips native_mode on so bash tools run natively. On boot, any task left running from a prior process is marked interrupted.

Environment variables

The AURA_API_KEY / AURA_MODEL / AURA_BASE_URL block exists because the deploy path sets these on the docker run command — without it a fresh container would run against the default preset with nothing listening. Empty values are ignored, so re-running the daemon without re-passing every variable doesn't wipe settings.

Examples

# Full daemon on the default port, with bearer auth and a cloud provider
AURA_WEB_TOKEN=$(uuidgen) \
AURA_API_KEY=sk-... AURA_MODEL=deepseek-chat AURA_BASE_URL=https://api.deepseek.com \
aura-daemon

# Override the web port
aura-daemon --port 9000

# Strict remote deployment serving the viewer SPA
AURA_WEB_TOKEN=... AURA_REMOTE_DEPLOYMENT=true aura-daemon

Docker CLI flags (daemon image)

For remote agent deployments, prefer the deploy_remote tool over a hand-rolled docker run. See Deployment & Security.

Command-line diagnostics

# Health (public)
curl http://localhost:18800/api/health

# Full diagnostics (auth)
curl http://localhost:18800/api/diagnostics -H "Authorization: Bearer $TOKEN" | jq

# Prometheus metrics
curl http://localhost:18800/api/metrics -H "Authorization: Bearer $TOKEN"

# OpenAPI spec
curl http://localhost:18800/api/openapi.json -H "Authorization: Bearer $TOKEN" | jq

Native helper sidecars

Alongside aura-daemon, the desktop build bundles a few small native binaries that back specific tools. They aren't invoked directly in normal use — the agent runtime calls them.

There is no aura-inference sidecar and no aura-cli TUI — both were removed with local model inference.

Network ports

These are the ports Aura Workshop itself binds:

Data storage locations

Aura Workshop keeps a single SQLite database plus a handful of file-based directories. The database path is platform-specific:

The database runs in WAL (Write-Ahead Logging) mode — concurrent reads with a single writer. Credentials and OAuth tokens are stored encrypted (AES-256-GCM).

Database

A single SQLite database holds all application state — 63 base tables plus 6 FTS5 full-text indexes. The schema is created and migrated automatically on launch (CREATE TABLE IF NOT EXISTS plus idempotent ALTER TABLE … ADD COLUMN blocks), so no manual migration step is ever required. The tables group into these domains:

For the full entity-relationship model, see the architecture reference in the repository documentation.

License tiers

Aura Workshop runs fully in its base tier with no license key. Entering a key in Settings → Security unlocks higher tiers; features for the new tier become available immediately without a restart.

Managed devices can also receive their tier and policy from the Enterprise Portal — enrollment sets the org and syncs spend limits and routing rules locally. Feature availability by tier is subject to change; the product pages carry current commercial terms.

Troubleshooting & FAQ

Most issues follow a symptom → where to look shape. Start here, then check the relevant settings or REST route.

macOS quarantine prevents launch

macOS may quarantine a freshly-installed app ("… cannot be opened because it is from an unidentified developer"). Clear the attribute, then relaunch:

xattr -cr "/Applications/Aura Workshop.app"

Useful queries

-- Running tasks (including autonomous)
SELECT id, title, status, task_mode FROM tasks WHERE status = 'running';

-- Armed autonomous loops
SELECT id, next_run_at, enabled FROM scheduled_tasks WHERE id LIKE 'loop-%';

-- Recent token usage
SELECT provider, model, SUM(input_tokens + output_tokens) AS tokens, SUM(cost_usd) AS cost
FROM token_usage WHERE created_at > datetime('now', '-24 hours')
GROUP BY provider, model ORDER BY cost DESC;

-- ACP peers discovered but not admitted
SELECT peer_id, agent_name, source, enabled, health FROM acp_agents WHERE enabled = 0;

Frequently asked

My agent doesn't remember things across tasks. Is memory broken?
Usually not. memory_enabled may be on but embeddings are off by default, so recall is lexical only — a differently-worded query won't match. Team-scoped facts also need a matching active_team_id. See Memory & Knowledge.

The knowledge graph is empty even after days of use.
The concept graph and code graph are built on demand (POST /api/concept-graph/build, POST /api/codegraph/scan), not passively.

Can I run Aura Workshop fully offline?
Yes — point it at a local OpenAI-compatible server (Ollama, LM Studio, vLLM) as a custom provider. All data stays on your machine; no cloud provider is required.

Where do I see why the router picked a model?
GET /api/routing/stats for the tier, and the routing_decisions table (Routing Debug Log UI) for the full per-request record.

Diagnostics & bug reports

GET /api/diagnostics returns provider connectivity, MCP statuses, daemon status, disk, and recent errors. Help → Generate bug report (or POST /api/generate-bug-report) bundles the app version, platform info, recent logs, a secrets-redacted settings snapshot, and diagnostics — email it to [email protected].