Getting Started

This chapter walks you through the essential steps to get your first BinaryCircuits‑compiled workflow up and running, whether you are:

• Running a single workflow binary on your own machine, or
• Using the BinaryCircuits user app and controller to manage multiple workflows.

You do not need to know anything about n8n internals or Rust to follow along.

System Requirements

Compiled workflows are highly portable and have minimal requirements:

• A compatible operating system (Linux, macOS, or Windows).
• Sufficient memory and CPU for the workload (most workflows are very lightweight; typical usage is similar to running a small CLI tool).
• No external dependencies like Node.js, Python, or even an n8n instance are required.

If you use the user TUI/CLI or controller, you will also need:

• A reasonably recent terminal emulator.
• Network access from the TUI/CLI to the BinaryCircuits API (for login, marketplace browsing, etc.).

Two Ways to Use BinaryCircuits

There are two primary ways you will interact with BinaryCircuits:

1. Direct binaries – you download a compiled workflow binary and run it like any other program. This offers maximum simplicity and self-containment.
2. Managed workflows – you use the BinaryCircuits user app and controller to browse, install, and run workflows in a more automated and centralized way. This provides enhanced management and automation capabilities.

You can mix and match these approaches. Many users start with direct binaries, then move to the controller once they have a handful of workflows they rely on.

Option 1: Using a Downloaded Binary

When you acquire a workflow from the BinaryCircuits marketplace, you receive a single, executable binary file (and optionally a small README and metadata file that describes the workflow).

Step 1 – Download the Binary

From the BinaryCircuits marketplace or user app:

• Choose the workflow you want.
• Select the appropriate build for your operating system and architecture (for example: linux-x86_64, macos-aarch64, or windows-x86_64).
• Download the binary file (for example, email-reporter-linux, email-reporter.exe).

Step 2 – Place It Somewhere Sensible

Move the file to a convenient location on your system. Common choices:

• A dedicated ~/workflows/ directory.
• A directory that is included in your system PATH, such as /usr/local/bin (Linux/macOS) or a tools folder on Windows that is already on PATH.

Step 3 – Make It Executable (Linux/macOS)

On Linux and macOS, you may need to give the file execute permissions. In a terminal:

chmod +x /path/to/your/email-reporter-linux

On Windows, the downloaded file will typically already be executable (for example, email-reporter.exe).

Step 4 – Run the Workflow

Most workflows can be run directly:

/path/to/your/email-reporter-linux

If a workflow expects input, it will either:

• Prompt you interactively, or
• Expect JSON input via standard input or a simple flag (for example, passing a JSON file path).

The exact behaviour for a given workflow is documented in its marketplace description. A typical pattern is:

cat input.json | /path/to/your/email-reporter-linux

The workflow will execute its logic and, if it produces an output, will usually print the result as a JSON string to the terminal. You can then:

• Pipe the output into another tool.
• Save it to a file.
• Feed it into other systems.

Option 2: Using the BinaryCircuits User App

For day‑to‑day usage, especially if you manage multiple workflows, the BinaryCircuits user TUI/CLI is the recommended way to interact with the platform.

The user app runs in your terminal and lets you:

• Log in to your BinaryCircuits account.
• Browse and search the marketplace.
• See details for each workflow (description, pricing, inputs/outputs, example usage).
• Add workflows to a cart and purchase them (or claim free ones).
• Download compiled binaries associated with your account directly through the app.

Typical Flow in the User App

1. Launch the app

   tui_user   # or the equivalent launcher on your system
   

2. Log in or register

   • Use the login/registration screen to authenticate with your email and password.
   • Your subscription tier determines which workflows you can access.

3. Browse and search

   • Use the browse screen to filter by category (AI, DevOps, Finance, etc.).
   • Search for keywords like “Slack”, “invoice”, or “webhook”.

4. Inspect a workflow

   • Open the workflow details screen to see:
     • A high‑level description.
     • What inputs it expects.
     • What outputs it produces.
     • Pricing and licence information.

5. Acquire the workflow

   • Add it to your cart and check out, or claim it if it is free and your tier includes it.

6. Download and Configure

   • From the app’s library or workflow details, you can:
     • Download the compiled binary to a local directory.
     • Optionally configure it to be managed and run by the controller (e.g., set up schedules or webhooks).

The exact keybindings and screens may evolve over time, but the core idea remains: the user app is your “front door” into the BinaryCircuits ecosystem.

Running Workflows via the Controller

For more advanced scenarios—such as scheduling, webhook triggers, or centralised monitoring—you will use the BinaryCircuits Controller.

Think of the controller as a small service that:

• Knows where each compiled workflow binary lives.
• Starts workflows when triggers fire (manual, HTTP, cron).
• Collects exit status and basic logs for each run.

When to Use the Controller

Use the controller if you:

• Want to expose a stable HTTP endpoint for a workflow (for example, as a webhook).
• Need to run workflows on a schedule (every hour, once per day, etc.).
• Want a single place to see which workflows ran, when, and with what result.

Basic Workflow with the Controller

1. Start the controller

   controller   # binary name may differ depending on your packaging
   

   By default, it runs as a long‑lived process and exposes HTTP and/or gRPC APIs.

2. Register or configure a workflow

   • You can register a workflow with the controller using the BinaryCircuits user app, or a dedicated CLI tool. This process typically involves telling the controller:
     • The path to your compiled workflow binary.
     • What kind of trigger it should listen for (manual, webhook, scheduled).
     • Any default input or configuration parameters the workflow needs.

3. Trigger the workflow

   • From a CLI helper (for example, a n8n-trigger‑style tool):

     n8n-trigger my-workflow-id --input '{"user_id": 42}'
     

   • Or by calling the controller’s HTTP API from your own systems (for example, a POST to /api/trigger/{workflow_id}).

4. Monitor the run

   • Use the controller’s APIs or future TUI integrations to:
     • Check whether a run succeeded or failed.
     • Inspect basic logs and output.

For production environments, the controller‑based approach is preferred because it centralises execution and simplifies monitoring.

Next Steps

Once you are comfortable running a single workflow, you can:

• Explore the Core Concepts chapter to better understand workflows, nodes, and triggers.
• Read the Pricing & Subscriptions chapter to choose the right tier.
• Use the controller to start building a small “fleet” of workflows that automate different parts of your infrastructure or business.