Halogent CLI

Private AI Agent Control Plane on Solana

Halogent is a privacy-first platform for deploying, managing, and orchestrating autonomous AI agents. The CLI connects your local or cloud runtime to the Halogent control plane, giving you full command-line access to your agents.

Your data never leaves your hands. Zero telemetry. Full ownership.

Installation

Via npm (recommended)

npm install -g halogent

Via curl

curl -fsSL https://halogent.tech/install.sh | bash

Verify installation

halogent --version

Quick Start

# 1. Authenticate with your API key
halogent auth set-key hlg_live_your_api_key_here

# 2. Pull agent configuration from the control plane
halogent agent pull <agent-id>

# 3. Start the agent runtime
halogent agent start <agent-id>

Commands

Authentication

| Command | Description | |---------|-------------| | halogent auth set-key <key> | Save your API key for runtime authentication | | halogent auth login | Interactive login with email OTP |

Agent Management

| Command | Description | |---------|-------------| | halogent agent pull <id> | Pull agent configuration from the control plane | | halogent agent start <id> | Start agent runtime and connect to the control plane | | halogent agent stop <id> | Stop a running agent runtime | | halogent agent status <id> | Check agent status on the control plane | | halogent agent dev <id> | Start agent in development mode with hot-reload |

Monitoring

| Command | Description | |---------|-------------| | halogent dashboard | View full dashboard in terminal with live data |

Infrastructure

| Command | Description | |---------|-------------| | halogent init | Initialize a new agent workspace | | halogent service install <id> | Generate a systemd service file for auto-start | | halogent config set-endpoint <url> | Set a custom control plane URL |

Configuration

The CLI stores configuration in ~/.halogent/config.json:

{
  "apiKey": "hlg_live_...",
  "endpoint": "https://halogent.tech"
}

Environment Variables

| Variable | Description | |----------|-------------| | HALOGENT_API_KEY | API key for authentication | | HALOGENT_ENDPOINT | Control plane endpoint URL | | HALOGENT_PRIVACY_MODE | Privacy mode: strict, standard, or permissive | | HALOGENT_MEMORY_MODE | Memory mode: local or cloud |

Agent Lifecycle

1. Create an agent via the Halogent Dashboard
2. Deploy the agent to generate an API key and deployment record
3. Pull the agent config to your local machine or VPS
4. Start the runtime: it connects to the control plane and begins executing
5. Monitor via the dashboard command or web UI
6. Stop when done: the control plane is notified automatically

Deployment Options

Local Development

halogent agent dev <agent-id>

VPS / Cloud Server

# Pull and start
halogent agent pull <agent-id>
halogent agent start <agent-id>

# Or install as a systemd service for auto-restart
halogent service install <agent-id>
sudo systemctl enable halogent-<agent-id>
sudo systemctl start halogent-<agent-id>

Docker

FROM node:20-alpine
RUN npm install -g halogent
ENV HALOGENT_API_KEY=hlg_live_your_key
CMD ["halogent", "agent", "start", "your-agent-id"]

API Key Format

API keys follow the format: hlg_live_ followed by a 36-character hex string.

hlg_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8

Keys are generated when you deploy an agent from the dashboard. You can regenerate keys at any time from the agent detail page.

Runtime Authentication

The CLI authenticates with the control plane using the X-Halogent-Key HTTP header:

# Example: manually check agent status via API
curl -H "X-Halogent-Key: hlg_live_your_key" \
  https://halogent.tech/api/v1/agent/<id>/status

Runtime API Endpoints

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/v1/agent/:id/config | Pull agent configuration | | POST | /api/v1/agent/:id/start | Notify control plane runtime is starting | | POST | /api/v1/agent/:id/stop | Notify control plane runtime is stopping | | POST | /api/v1/agent/:id/heartbeat | Send heartbeat from runtime | | GET | /api/v1/agent/:id/status | Get agent status |

Privacy & Security

• Zero telemetry: no usage data is collected or transmitted
• Local-first: agent memory and data stay on your machine by default
• Encrypted connections: all communication with the control plane uses HTTPS
• Key rotation: regenerate API keys at any time from the dashboard
• Privacy modes: choose between strict, standard, and permissive data handling

Requirements

• Node.js >= 18.0.0
• An active Halogent account
• At least one deployed agent with an API key

Workspace Initialization

Run halogent init to set up a new workspace. This creates:

• .env file with configuration placeholders
• .gitignore with sensible defaults

mkdir my-agent && cd my-agent
halogent init

Troubleshooting

Cannot connect to the control plane

# Check your endpoint configuration
cat ~/.halogent/config.json

# Test connectivity
curl https://halogent.tech/api/public/live-agents

API key not working

# Re-set your API key
halogent auth set-key <your-new-key>

# Or regenerate from the dashboard

Agent not starting

# Check agent status on the control plane
halogent agent status <agent-id>

# Pull latest configuration
halogent agent pull <agent-id>

Links

• Dashboard
• Documentation
• Install Guide
• GitHub
• X / Twitter

License

MIT