Halo Agent setup guide

Prerequisites

• Node.js 20+ — required for npm and the CLI
• Ollama running locally (default http://127.0.0.1:11434)
• A tool-capable model installed, e.g. ollama pull llama3.2 or ollama pull qwen3-coder:30b
• Optional: Aura Wire on Windows — for IDE integration and routed cloud backends via custom providers

Halo Agent uses only Node built-ins at runtime — no extra npm dependencies after install.

Installation

Recommended: install the published package globally so halo-agent is on your PATH.

npm install -g @halosoftworks/halo-agent
halo-agent models
halo-agent "what time is it right now?"

Try without installing

Use npx for a one-off run — useful for scripts or CI:

npx @halosoftworks/halo-agent "summarize README.md"

Offline or air-gapped

Download the versioned .zip from Extras or direct download, extract it, and use the launchers in bin/ (halo-agent.ps1, halo-agent.cmd, halo-agent.sh).

Halo Agent is proprietary software — free for personal, non-commercial use. See the Halo Softworks EULA.

First run

1. Start Ollama and confirm a model is installed (ollama list).
2. Run halo-agent models to see how auto model selection classifies your installed models.
3. Ask a simple question: halo-agent "what time is it right now?"
4. In a project folder, try a file task: halo-agent "list the largest files here"

By default, interactive terminals use ask mode — file writes and shell commands prompt for y/N approval. Scripts and serve mode use unattended agent mode.

OpenAI-compatible server

Expose the agent loop behind the standard OpenAI API so any HTTP client — or an Aura Wire routing rule — can call it:

halo-agent serve --port 11435

• POST /v1/chat/completions — messages in, full agent loop (with tools) runs, chat.completion out. Streaming is supported via SSE replay.
• GET /v1/models — lists installed Ollama models.

Serve mode always runs unattended. Put Aura Wire guardrails in front if you need policy on tool execution or outbound traffic.

Pair with Aura Wire

Halo Agent is standalone — it does not require Aura Wire. Wire is the pairing that completes the IDE and cloud story:

1. Run halo-agent serve on a port you choose (default example: 11435).
2. In Aura Wire, open Pipeline → Aura Router → Custom providers and add an OpenAI-compatible HTTP endpoint pointing at your serve URL.
3. Create a routing rule that sends agentic traffic to that provider — local Ollama stays free; cloud backends cost only what you route.
4. Point editors at Aura Wire's /v1 door (redirect or direct). Wire routes to Halo Agent; no editor-specific extension is required from Halo Agent.

One chat completion in = one full agent run out. Declare capabilities honestly on the provider row — Halo Agent executes tools itself, so client-side tool_calls stays unchecked (same convention as Wire's built-in agent runtimes).

See the Aura Wire setup guide for proxy and IDE configuration.

SDK

Embed the same loop in your own software — install the package locally in a project or import after global install:

npm install @halosoftworks/halo-agent

import { createAgent } from "@halosoftworks/halo-agent";

const agent = await createAgent({
  model: "qwen3-coder:30b",
  workspaceRoot: "/path/to/project",
});

const { text } = await agent.run("run the tests and fix any failure");

Lower-level exports (AgentLoop, McpClient, createOpenAIServer, etc.) are available for custom wiring. See the package README on npm for the full API surface.

Common CLI options

• --model <name|auto> — Ollama model (default auto picks the best installed tool-capable model)
• --cwd <path> — workspace root for file and shell tools
• --mode ask|agent — confirm writes/shell in ask mode; unattended in agent mode
• --session <name> — persist and resume a conversation in the workspace
• --mcp "<command>" — attach an MCP server over stdio (repeatable)
• --max-steps <n> — cap model round-trips (default 10)

Troubleshooting

• Ollama connection errors — confirm Ollama is running and --base-url matches (default http://127.0.0.1:11434).
• Weak or missing models — run halo-agent models; pull a larger tool-capable model or pass --model explicitly.
• Context overflows — Ollama's default context is small; use --num-ctx (default 16384) or enable compaction via sessions on long tasks.
• Wire cannot reach serve — use a loopback URL Wire can access; check firewall rules if serve runs in Docker (try host.docker.internal from containers).