AviFlow documentation

Everything the tool does, stated plainly — including what it deliberately does not do.

Quick start

1. Open the builder. No account, nothing to install.
2. Load an example workflow (real workflows shipped with the engine), or start from a blank one.
3. Edit steps: each step has a kind, an optional connector, an approval policy, and a budget estimate.
4. Press Validate — the builder checks your workflow against the exact schema the engine executes.
5. Press Run sandbox — a deterministic simulation runs in your browser. When a step requires approval, the run pauses and asks you.
6. Export the JSON and run it for real with the engine CLI (below), or keep iterating — drafts autosave to your browser's local storage.

The workflow format

An AviFlow workflow is one plain JSON file. You can write it by hand, version it in git, and diff it in code review.

{
  "id": "welcome_new_lead",
  "name": "Welcome a new lead",
  "version": "1.0.0",
  "connectors": [{ "name": "email", "config": {} }],
  "budget_policy": {
    "max_tokens_usd": 2, "max_api_usd": 3, "max_time_s": 300,
    "hard_stop": true
  },
  "steps": [
    {
      "id": "score_lead",
      "kind": "decision",
      "input_mapping": { "condition": "lead.qualified" },
      "output_mapping": { "steps.score_lead.decision": "decision" },
      "approval_policy": { "mode": "auto", "risk_level": "low" },
      "budget_estimate": { "tokens_usd": 0.001, "api_usd": 0, "time_s": 1 },
      "idempotency_key": "{{workflow_id}}:{{run_id}}:score_lead",
      "metadata": {}
    },
    {
      "id": "send_welcome",
      "kind": "tool_call",
      "connector": "email",
      "input_mapping": { "decision": "steps.score_lead.decision" },
      "output_mapping": { "steps.send_welcome.message_id": "message_id" },
      "approval_policy": { "mode": "needs_approval", "risk_level": "high" },
      "budget_estimate": { "tokens_usd": 0.001, "api_usd": 0.004, "time_s": 2 },
      "idempotency_key": "{{workflow_id}}:{{run_id}}:send_welcome",
      "metadata": {}
    }
  ]
}

Fields that carry the guarantees

Field	What it enforces
approval_policy	auto runs freely; needs_approval always pauses for a human; risk_based pauses unless risk_level is low. The engine evaluates this — a workflow cannot opt out of its own gate at run time.
budget_policy / budget_estimate	Before each step, projected spend is checked against the workflow's caps. With hard_stop: true the run fails at the ceiling instead of overshooting it.
idempotency_key	A completed step's output is cached under this key. Re-running the same key reuses the cached output — a retry cannot double-send.
input_mapping / output_mapping	Dot-paths that read from and write to the run context. All data flow is explicit and inspectable; there is no hidden state.

Step kinds

• tool_call — invokes a connector (http, email, crm).
• decision — evaluates its condition input to a boolean and records why.
• transform — reshapes data; output includes a hash of what it transformed.
• notify — records a notification event to a channel named in metadata.channel.

Sandbox semantics — what a browser run really is

The Run sandbox button in the builder executes your workflow with the engine's semantics — approval gates, budget caps, idempotency reuse, audit events, deterministic seeded outputs — entirely in your browser.

• It makes zero external network calls. An email step in the sandbox produces a message record in the run output; it does not and cannot send mail.
• It is deterministic: the same workflow with the same seed produces the same run, including the same final context hash.
• Every run output is labeled mode: "sandbox" so a sandbox result can never be mistaken for a live one.

Running for real: the engine CLI

The AviFlow engine lives in the open Avieros repository at ops/pilotflow and runs locally with Node 22+. It executes workflow files from ops/pilotflow/workflows/ with file-backed state: an append-only audit log, an approvals queue, an idempotency store, and per-run state files.

# run a workflow (risky steps will queue approvals unless auto-approved)
node ops/pilotflow/cli.ts run --workflow sales_funnel --seed demo-1

# list pending approvals, then decide
node ops/pilotflow/cli.ts approvals:list --status=pending
node ops/pilotflow/cli.ts approvals:approve --id apr_xxxxxxxxxxxx --reason "reviewed"

# verify a past run reproduces byte-for-byte
node ops/pilotflow/cli.ts replay --run_id pf_sales_funnel_xxxxxxxxxx --seed demo-1

Honest boundary: the engine's bundled connectors currently execute against sandboxed targets — email appends to a local outbox file, crm appends to a local events file, http returns a deterministic simulated response. Every response identifies itself as such. Live provider sends ship only behind the Avieros approval runtime, and nothing in AviFlow pretends otherwise.

Importing from n8n

Export any n8n workflow as JSON, then paste it into the builder's Import n8n panel (or run node ops/pilotflow/convert-n8n.ts convert-n8n --input flow.json --output out.json). The converter:

• maps n8n nodes to AviFlow step kinds and connectors (HTTP request, email/SMTP/Gmail/SendGrid, CRM, IF/Switch, Function/Set, Slack/Telegram notifications);
• preserves node dependency order from the n8n connection graph in each step's metadata.depends_on;
• flags every external-touching node (email, HTTP, SMS, ads…) as needs_approval / risk_level: high — imported automations don't inherit n8n's run-free defaults;
• derives a conservative per-step budget and a hard-stop budget policy at 2× the estimated total;
• validates the result against the engine schema before giving it to you.

The builder bundles the same converter module the CLI uses — one implementation, test-enforced in the repository.

The honesty rules

AviFlow inherits the Avieros platform's non-negotiable rule: never fabricate success. Concretely:

• A connector that cannot make a call reports ok:false with a reason. There is no code path that reports "connected" or "sent" without the thing having happened.
• Sandbox output is always labeled sandbox. Simulated HTTP responses carry a simulated_source marker in the payload itself.
• The What's real today section on the landing page is maintained as a product surface. If it says NOT LIVE, no page on this site will imply otherwise.

Questions, early access, or a claim you'd like to challenge: founder.avieros@gmail.com.