Registry / llm-agents / helix-agent-framework

helix-agent-framework

library0.10.0jsnpmunverified

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.

llm-agents ai-ml auth-security workflow database

npm install helix-agent-framework

package ↗homepage ↗

INSTALL

IMPORT

SIG · HELIX-AGENT-FRAMEW

helix-agent-framework

llm-agentsjavascriptv0.10.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

startHelixRuntime

✓ import { startHelixRuntime } from 'helix-agent-framework';

✗ const Helix = require('helix-agent-framework'); Helix.startRuntime();

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

✓ import { getLLMProvider } from 'helix-agent-framework';

✗ import { LLMProvider } from 'helix-agent-framework/llm-provider';

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

✓ import { AgentManager } from 'helix-agent-framework';

✗ const { AgentManager } = require('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.

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/

helix --version

Debug

Known issues

breakingAs 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.

affects: <1.0.0

gotchaHelix 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.

affects: >=0.1.0

gotchaAPI 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.

affects: >=0.1.0

gotchaThe 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.

affects: >=0.1.0

gotchaHelix 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.

affects: >=0.1.0

Errors

Common errors & fixes

command not found: helix

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.

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

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.

Upgrade

Version history

0.10.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://www.npmjs.com/package/helix-agent-framework ↗

homepagehttps://helix.ml ↗