Headless & Server Mode

Run Huginn without a terminal UI — in shell scripts, CI pipelines, Docker containers, and always-on background servers.

The three modes

Huginn gives you three ways to run without a human in front of a keyboard.

Single-turn mode

Send one message, get one response, exit. That’s it.

huginn --print "what does the auth middleware do?"
# Short form
huginn -p "summarize internal/payment/gateway.go"

The process exits with code 0 on success. Use it anywhere you’d use a shell command that returns output.

JSON output

Add --json to get structured output you can pipe into jq or parse in a script.

huginn --headless --json --print "list all API endpoints"

The response comes back as a JSON object instead of plain text — useful when you need to extract specific fields downstream.

Run a specific agent

huginn --agent Elena --print "review internal/auth/ for injection risks"

The --agent flag works with --print. The named agent handles the request using its own tools and toolbelt.

Headless mode

No TUI. Output goes to stdout. Combine with --print to run a single turn, or with --command to run a slash command on start.

# Single question, plain text output
huginn --headless --print "what changed in the last 10 commits?"

# JSON output, pipe to jq
huginn --headless --json --print "list all exported functions in pkg/auth" | jq '.response'

Headless mode still runs the full agentic loop. The agent can use tools, read files, and search your codebase — you just don’t see the TUI chrome around it.

Server mode

huginn tray --server starts the web server and skips the onboarding wizard. No TUI, no interactive prompt. The web UI is served at http://localhost:8421 and keeps running until the process is stopped.

huginn tray --server

Use this for:

• Docker containers
• Linux servers with no TTY
• Machines you SSH into occasionally but want Huginn always running

To start the server without the system tray icon (common on headless Linux):

huginn tray --server --no-tray

Always use --server in Docker. Without it, Huginn waits for onboarding input on startup and blocks indefinitely.

CI/CD usage

GitHub Actions

- name: Code review
  run: |
    huginn --headless --json --print "review the diff in this PR for security issues" \
      | jq -r '.response' >> $GITHUB_STEP_SUMMARY
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    HUGINN_CLOUD_TOKEN: ${{ secrets.HUGINN_CLOUD_TOKEN }}

Makefile

.PHONY: audit
audit:
	huginn --print "check pkg/auth for missing nil guards and report findings"

.PHONY: docs-check
docs-check:
	huginn --headless --json --print "list undocumented exported functions" | jq '.response'

Skipping permission prompts in CI

In a CI environment there is no user to approve tool calls. Use --dangerously-skip-permissions to let the agent write files and run commands without prompting.

huginn --dangerously-skip-permissions --print "run the test suite and fix any failures"

Only use --dangerously-skip-permissions inside an isolated environment — a container, a CI runner, a sandboxed VM. The flag disables every approval checkpoint. On a developer machine with production credentials in the environment, that is a serious risk.

Docker deployment

A minimal Dockerfile for an always-on Huginn server:

FROM ubuntu:22.04

COPY huginn /usr/local/bin/huginn

# Required: expose the web UI beyond localhost
ENV HUGINN_CLOUD_URL=https://api.huginncloud.com

EXPOSE 8421

CMD ["huginn", "tray", "--server", "--no-tray"]

Build and run:

docker build -t my-huginn .
docker run -p 8421:8421 \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e HUGINN_CLOUD_TOKEN=fleet-token-here \
  my-huginn

The web UI is available at http://localhost:8421 on the host.

Bind address

By default Huginn binds to 127.0.0.1 — unreachable from outside the container. Set web.bind in your config to expose it:

{
  "web": { "bind": "0.0.0.0" }
}

Mount or bake this config into the container at ~/.huginn/config.json. Without this, the port is open on the host but the container refuses connections.

Environment variables

API keys for your LLM provider go in the standard environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.). Reference them in ~/.huginn/config.json using the $ENV_VAR syntax:

{
  "backend": {
    "type": "external",
    "provider": "anthropic",
    "api_key": "$ANTHROPIC_API_KEY"
  }
}

Quick reference

# Ask a question without the TUI
huginn --print "what does the payment service do?"
huginn -p "summarize cmd/main.go"

# JSON output for parsing
huginn --headless --json --print "list all HTTP handlers"

# Run a specific agent
huginn --agent Elena --print "review pkg/auth for vulnerabilities"

# Server for Docker / remote machines
huginn tray --server
huginn tray --server --no-tray

# CI — skip prompts (use in isolated environments only)
huginn --dangerously-skip-permissions --print "run tests and fix failures"

# Fleet deployment with a pre-issued token
HUGINN_CLOUD_TOKEN=fleet-token-here huginn tray --server --no-tray