Helix AI Agent Framework

0.10.0 · active · verified Tue Apr 21

Helix is a local-first AI agent framework designed for project workspaces, enabling the creation and execution of AI agents entirely on your machine using SQLite, without reliance on cloud services or external databases like PostgreSQL. Currently at version 0.10.0, the framework offers a comprehensive suite of features including a robust agent runtime with persistent memory, support for 10 major LLM providers (Gemini, Claude, OpenAI, etc.) with SSE streaming, Plan-Act-Observe reasoning, a three-tier memory system, and a DAG-based workflow engine. It differentiates itself through its strong focus on local execution, extensive security features (command safety, prompt injection defense, 2FA, RBAC, OAuth), and a rich set of developer tools like an evaluation framework, tracing, and a web dashboard. While no explicit release cadence is stated, its feature set and ongoing development imply active maintenance with frequent updates expected before a stable 1.0 release.

Common errors

```
command not found: helix
```
cause The Helix CLI was not installed globally or is not in your system's PATH.

fix Run `npm install -g helix-agent-framework` to install the CLI globally. Ensure your npm global bin directory is in your system's PATH.
```
Error: API key for provider 'gemini' is not set. Please set GEMINI_API_KEY.
```
cause The required API key for the specified LLM provider (e.g., Gemini) has not been configured.

fix Use `helix login --provider gemini --api-key YOUR_KEY` or set the corresponding environment variable (e.g., `export GEMINI_API_KEY=YOUR_KEY`) before starting the runtime or interacting with agents.
```
EADDRINUSE: address already in use :::18860
```
cause Another process is already using the default port (18860) that Helix attempts to bind to.

fix Identify and terminate the process using port 18860, or configure Helix to use a different port (e.g., `helix start --port 18861`), if supported by the framework's configuration options.

Warnings

breaking As a pre-1.0 release (v0.10.0), `helix-agent-framework` is subject to frequent breaking changes in minor and patch versions. API signatures, configuration formats, and internal behaviors may change without strict adherence to semantic versioning until a stable 1.0 release.
Fix: Always review the release notes and migration guides (if available) when upgrading to a new version. Pin exact versions in your `package.json` to prevent unexpected breakage.
gotcha Helix uses SQLite for local-first data storage. Upgrading the framework may introduce database schema changes that require manual migration or could lead to data loss if not handled correctly. Backups are crucial.
Fix: Before upgrading, always back up your workspace data using `helix export > backup.json`. Check release notes for any explicit migration steps for SQLite database schemas.
gotcha API keys for LLM providers are critical for agent functionality. Incorrectly setting `API_KEY` environment variables or using `helix login` with the wrong provider/key will prevent agents from working.
Fix: Ensure `helix login` is used correctly for each provider, or that environment variables (e.g., `GEMINI_API_KEY`) are precisely matched to the LLM model being used. Use `helix doctor` to check environment configurations.
gotcha The local runtime listens on port 18860 by default. If this port is already in use by another application, `helix start` will fail, preventing the dashboard and agents from launching.
Fix: Check for other applications using port 18860. If necessary, you may need to configure Helix to use an alternative port (consult documentation for configuration options) or terminate the conflicting process.
gotcha Helix offers robust security features like Command Safety, which detects 35+ dangerous patterns in shell commands. This can sometimes block legitimate but unusual commands if not configured correctly or if custom tools generate risky patterns.
Fix: If agents are blocked from executing commands, review the logs for 'Command Safety' warnings. Adjust the safety configuration or whitelist specific command patterns with caution, understanding the security implications.

Install

npm install helix-agent-framework npm
yarn add helix-agent-framework yarn
pnpm add helix-agent-framework pnpm

Imports

startHelixRuntime
wrong:
```
const Helix = require('helix-agent-framework'); Helix.startRuntime();
```
correct:
```
import { startHelixRuntime } from 'helix-agent-framework';
```
For programmatic initialization and management of the core Helix runtime within a Node.js application, rather than using the CLI `helix start` command. This assumes a primary export for the runtime.
getLLMProvider
wrong:
```
import { LLMProvider } from 'helix-agent-framework/llm-provider';
```
correct:
```
import { getLLMProvider } from 'helix-agent-framework';
```
Allows programmatic access to the unified LLM abstraction layer for interacting with various models directly, bypassing the full agent reasoning loop. The exact function name is inferred as a common pattern for obtaining a service instance.
AgentManager
wrong:
```
const { AgentManager } = require('helix-agent-framework');
```
correct:
```
import { AgentManager } from 'helix-agent-framework';
```
Provides an interface to programmatically manage agent instances, including spawning, querying their status, and interacting with their memory, when building custom agent orchestrations or extensions.

Quickstart

Initializes a new Helix project, configures an LLM API key, and starts the local AI agent runtime and web dashboard.

npm install -g helix-agent-framework

# 1. Initialize your project workspace
helix init

# 2. Configure an API key for an LLM provider (e.g., Gemini)
helix login --provider gemini --api-key YOUR_GEMINI_API_KEY

# You can also set it via environment variable for production:
# export GEMINI_API_KEY=YOUR_KEY

# 3. Start the local Helix agent runtime
helix start

# Access the dashboard at http://localhost:18860/v2/

view raw JSON →