{"id":15639,"library":"helix-agent-framework","title":"Helix AI Agent Framework","description":"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.","status":"active","version":"0.10.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","ai","agent","framework","helix","local-first"],"install":[{"cmd":"npm install helix-agent-framework","lang":"bash","label":"npm"},{"cmd":"yarn add helix-agent-framework","lang":"bash","label":"yarn"},{"cmd":"pnpm add helix-agent-framework","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Helix = require('helix-agent-framework'); Helix.startRuntime();","symbol":"startHelixRuntime","correct":"import { startHelixRuntime } from 'helix-agent-framework';"},{"note":"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.","wrong":"import { LLMProvider } from 'helix-agent-framework/llm-provider';","symbol":"getLLMProvider","correct":"import { getLLMProvider } from 'helix-agent-framework';"},{"note":"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.","wrong":"const { AgentManager } = require('helix-agent-framework');","symbol":"AgentManager","correct":"import { AgentManager } from 'helix-agent-framework';"}],"quickstart":{"code":"npm install -g helix-agent-framework\n\n# 1. Initialize your project workspace\nhelix init\n\n# 2. Configure an API key for an LLM provider (e.g., Gemini)\nhelix login --provider gemini --api-key YOUR_GEMINI_API_KEY\n\n# You can also set it via environment variable for production:\n# export GEMINI_API_KEY=YOUR_KEY\n\n# 3. Start the local Helix agent runtime\nhelix start\n\n# Access the dashboard at http://localhost:18860/v2/","lang":"typescript","description":"Initializes a new Helix project, configures an LLM API key, and starts the local AI agent runtime and web dashboard."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The Helix CLI was not installed globally or is not in your system's PATH.","error":"command not found: helix"},{"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.","cause":"The required API key for the specified LLM provider (e.g., Gemini) has not been configured.","error":"Error: API key for provider 'gemini' is not set. Please set GEMINI_API_KEY."},{"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.","cause":"Another process is already using the default port (18860) that Helix attempts to bind to.","error":"EADDRINUSE: address already in use :::18860"}],"ecosystem":"npm"}