Running Automations

This guide explains how to use Cortex to run and manage your automation habits.

Overview

Cortex is the lightweight execution engine at the heart of Habits. Cortex is designed to be minimal and embeddable, perfect for serverless deployments, edge computing, or bundling into your own applications.

Cortex Engine - Lightweight Runtime Executor

Lightweight by Design

Cortex runs your workflows without the overhead of a full platform. Deploy it to AWS Lambda, Cloudflare Workers, or embed it directly in your SaaS product.

Triggers (Cues)

In the Habit Loop, the Cue is the trigger that initiates your automation. Habits supports multiple trigger methods:

Trigger Type	Description	Status
CLI	Execute workflows from the command line	Available
REST API	Trigger workflows via HTTP endpoints	Available
Bits Watchers	Event-based triggers from Habits bits	Available
ActivePieces Triggers	Event-based triggers from ActivePieces Pieces	WIP
n8n Triggers	Event-based triggers from n8n nodes	Idea Abandoned, won't be in Habits

CLI Triggers

The CLI is ideal for manual execution, cron jobs, CI/CD pipelines, and local testing:

bash

npx @ha-bits/cortex@latest execute ./showcase/marketing-campaign/config.json

REST API Triggers

The REST API is the primary method for integrating with external systems and services. See the Swagger OpenAPI section below for complete details about the generated endpoints. To run in server mode, use this command:å

bash

npx @ha-bits/cortex@latest server --config ./showcase/marketing-campaign/config.json

How to Run Cortex

There are three main ways to run Cortex depending on your use case:

1. Using nx (Local Development)

If you're developing locally and have cloned the repository, use nx to run Cortex:

bash

# Run the dev target (uses preconfigured test config)
npx nx dev @ha-bits/cortex --config=n8n-top-6

This is the recommended approach when:

You're actively developing or debugging Cortex
You need hot-reloading during development
You're contributing to the codebase

2. Using the Playground Script

For quickly testing habits within Docker and an example configurations, use the playground script:

bash

bash packages/cortex/server/playground/run.bash --config=./showcase/marketing-campaign/config.json

Available options:

--config=<path>: Specify the example to run (e.g., --config ./showcase/marketing-campaign/config.json)
The playground provides a preconfigured environment for testing

This is ideal for:

Trying out example workflows
Testing habit configurations
Quick prototyping without full setup

3. Using npx (Production/Standalone)

For production use or running Cortex as a standalone tool, use npx:

bash

npx @ha-bits/cortex

With additional options:

bash

# Run with a specific habit file
npx @ha-bits/cortex --habit ./path/to/habit.json

# Run with custom configuration
npx @ha-bits/cortex --config ./config.json

# Run on a specific port
npx @ha-bits/cortex --port 3000

This approach is best for:

Production deployments
Running Cortex without cloning the repository
CI/CD pipelines
Quick execution of habits

Cortex Components

Cortex consists of several components that work together to execute and manage habits:

Component	Path	Description
Web UI	`/manage`	Visual interface for managing and monitoring habits
API	`/api`	RESTful API for programmatic access
Swagger Docs	`/api/docs`	Interactive API documentation

Cortex Web UI

The Cortex UI provides a visual interface for managing your habits.

Accessing the UI

Navigate to /cortex in your browser to access the Cortex dashboard.

Dashboard Features

Habits List: View all available habits
Execution History: See past runs and their status
Real-time Monitoring: Watch habits execute in real-time
Logs: Access detailed execution logs

Running a Habit from the UI

Navigate to the Habits list
Select the habit you want to run
Click "Run" or "Execute"
Monitor the execution progress

Cortex API

Cortex provides a RESTful API for programmatic access to all functionality.

API Base URL

http://your-host/api

Common Endpoints

Method	Endpoint	Description
`GET`	`/misc/workflows`	List all habits
`GET`	`/misc/workflow/:id`	Get a specific habit
`POST`	`/api/:id`	Execute a habit
`GET`	`/misc/executions`	List execution history
`GET`	`/misc/executions/:id`	Get execution details

Example: Execute a Habit

bash

curl -X POST http://localhost:3000/api/my-habit-id \
  -H "Content-Type: application/json" \
  -d '{"input": {"key": "value"}}'

Example: Check Execution Status

bash

curl http://localhost:3000/misc/executions/execution-id

Swagger API Documentation

Cortex includes interactive API documentation powered by Swagger/OpenAPI.

Accessing Swagger Docs

Navigate to /api/docs in your browser to access the interactive documentation.

Swagger Docs OpenAPI Swagger - Auto-generated API documentation

Features

Interactive Testing: Try API calls directly from the browser
Schema Documentation: View request/response schemas
Authentication: Configure API keys for authenticated endpoints
Code Examples: Generate code snippets for various languages

Execution Modes

Manual Execution

Trigger habits manually through:

The Cortex UI "Run" button
API calls to the execute endpoint
CLI commands

Scheduled Execution

Set up habits to run on a schedule:

Open the habit in the UI
Navigate to "Schedule" settings
Configure the cron expression or interval

Webhook Triggers

Habits can be triggered via webhooks:

Enable webhook trigger for your habit
Copy the generated webhook URL
Send a POST request to trigger execution

bash

curl -X POST http://localhost:3000/api/webhooks/your-webhook-id \
  -H "Content-Type: application/json" \
  -d '{"event": "triggered"}'

Monitoring and Logs

Execution History

View all past executions in the Cortex UI:

Real-time Logs

Monitor habit execution in real-time:

Click on an active execution
View logs as they stream
See bit-by-bit progress

Error Handling

When a habit fails:

The execution is marked as "Failed"
Error details are captured
You can retry the execution from the point of failure

Configuration

Environment Variables

Configure Cortex behavior through environment variables or config file:

Variable	Description	Default
`PORT`	API server port	`3000`
`LOG_LEVEL`	Logging verbosity	`info`
`DATABASE_URL`	Database connection string	-

Config File

Cortex reads from config.json in the project root:

json

{
  "server": {
    "port": 3000
  },
  "execution": {
    "timeout": 30000,
    "retries": 3
  }
}

Best Practices

Monitor Executions: Regularly check execution history for failures
Set Timeouts: Configure appropriate timeouts for long-running habits
Use Webhooks: For event-driven automation, prefer webhooks over polling
Secure Your API: Use authentication for production deployments

Packing & Distributing

Pack your habits into portable formats for different deployment targets:

Format	Output	Use Case
`single-executable`	Standalone binary	FullStack, Frontend + backend, Server/CLI, no Node.js needed
`desktop`	Electron app	Desktop UI connecting to remote backend (or local execution: Early Access)
`mobile`	Cordova app	iOS/Android app connecting to remote backend (or local exeuction: Early Access)

bash

# Single executable binary (includes backend)
npx habits pack --config ./stack.yaml --format single-executable -o ./my-app

# Desktop app (frontend-only, connects to your backend)
npx habits pack --config ./stack.yaml --format desktop --backend-url https://api.example.com -o ./output

# Mobile app (frontend-only)
npx habits pack --config ./stack.yaml --format mobile --backend-url https://api.example.com --mobile-target android -o ./output

Desktop platforms: dmg, exe, appimage, deb, rpm, msi
Mobile targets: android, ios

Platform Requirements

Format	Requirements
`single-executable`	Node.js 20+ (build only), macOS requires code signing
`desktop`	Node.js 18+, electron-builder (auto-installed)
`mobile`	Cordova CLI (`npm i -g cordova`), Android SDK (gradle, etc) or Xcode

Mobile Setup

Android: Install Android Studio, set ANDROID_HOME, ensure gradle 8.x is available
iOS: macOS only, requires Xcode with command line tools

See Binary Export for details on single-executable binaries.

Next Steps

Review the Concepts guide to understand core terminology
Learn how to build habits in the Creating Habits guide
Binary Export - Package your habits as a standalone executable

Running Automations ​

Overview ​

Triggers (Cues) ​

CLI Triggers ​

REST API Triggers ​

How to Run Cortex ​

1. Using nx (Local Development) ​

2. Using the Playground Script ​

3. Using npx (Production/Standalone) ​

Cortex Components ​

Cortex Web UI ​

Accessing the UI ​

Dashboard Features ​

Running a Habit from the UI ​

Cortex API ​

API Base URL ​

Common Endpoints ​

Example: Execute a Habit ​

Example: Check Execution Status ​

Swagger API Documentation ​

Accessing Swagger Docs ​

Features ​

Execution Modes ​

Manual Execution ​

Scheduled Execution ​

Webhook Triggers ​

Monitoring and Logs ​

Execution History ​

Real-time Logs ​

Error Handling ​

Configuration ​

Environment Variables ​

Config File ​

Best Practices ​

Packing & Distributing ​

Platform Requirements ​

Next Steps ​

Running Automations

Overview

Triggers (Cues)

CLI Triggers

REST API Triggers

How to Run Cortex

1. Using nx (Local Development)

2. Using the Playground Script

3. Using npx (Production/Standalone)

Cortex Components

Cortex Web UI

Accessing the UI

Dashboard Features

Running a Habit from the UI

Cortex API

API Base URL

Common Endpoints

Example: Execute a Habit

Example: Check Execution Status

Swagger API Documentation

Accessing Swagger Docs

Features

Execution Modes

Manual Execution

Scheduled Execution

Webhook Triggers

Monitoring and Logs

Execution History

Real-time Logs

Error Handling

Configuration

Environment Variables

Config File

Best Practices

Packing & Distributing

Platform Requirements

Next Steps