Configuration

Human reads configuration from ~/.human/config.json. Environment variables override config values.

Config location

| Platform | Path | | ---------- | ---------------------------------- | | Unix/macOS | ~/.human/config.json | | Windows | %USERPROFILE%\.human\config.json |

Key sections

| Section | Description | | --------------------- | ---------------------------------------------------------- | | default_provider | Default AI provider (e.g. openai, anthropic, ollama) | | default_model | Default model name | | default_temperature | Sampling temperature (0.0–2.0, default 0.7) | | providers | Array of provider entries with name, api_key, base_url | | channels | Channel enablement (cli, telegram, discord, etc.) | | tools | Tool config (enabled_tools, disabled_tools, timeouts) | | memory | Memory backend (sqlite, markdown, none) | | mcp_servers | External MCP server connections (command, args per server) | | cron | Cron job scheduling (enabled, interval) | | security | Sandbox, autonomy level, resource limits | | autonomy | Action limits, workspace scoping | | gateway | Host, port, pairing, webhook HMAC | | tunnel | Tunnel provider (e.g. ngrok) | | runtime | Execution environment (native, docker, wasm) | | agent | Agent behavior (hula, metacognition, tool limits, …) |

`agent.hula`

When true (default), Human may run HuLa JSON programs for structured multi-step tool use, with policy checks and optional trace files. Set "hula": false under agent to disable.

Full guide: HuLa Programs.

Autonomy levels

Control how much the agent can do without approval via autonomy.level or security.autonomy_level (0–4):

| Level | autonomy.level | Behavior | | ----- | ---------------- | -------------------------------------------------------- | | 0 | readonly | No shell or file writes; read-only tools only | | 1 | supervised | Ask before destructive or high-impact commands (default) | | 2+ | full | Autonomous execution; use with caution |

Config example:

{
  "autonomy": {
    "level": "supervised",
    "workspace_only": true,
    "max_actions_per_hour": 20
  },
  "security": {
    "autonomy_level": 1
  }
}

Use HUMAN_AUTONOMY=0 (readonly) through 4 (full) to override via environment.

Environment variable overrides

These override config values when set:

| Variable | Overrides | | --------------------------- | --------------------------- | | HUMAN_PROVIDER | default_provider | | HUMAN_MODEL | default_model | | HUMAN_API_KEY | Default API key | | HUMAN_TEMPERATURE | default_temperature | | HUMAN_GATEWAY_PORT | gateway.port | | HUMAN_GATEWAY_HOST | gateway.host | | HUMAN_WORKSPACE | Workspace directory | | HUMAN_ALLOW_PUBLIC_BIND | gateway.allow_public_bind | | HUMAN_WEBHOOK_HMAC_SECRET | Webhook HMAC secret | | HUMAN_AUTONOMY | Autonomy level (0–4) |

Provider-specific keys (used when no HUMAN_API_KEY or provider-specific key in config):

OPENAI_API_KEY — OpenAI
ANTHROPIC_API_KEY — Anthropic
GEMINI_API_KEY — Google Gemini
OLLAMA_HOST — Ollama base URL (e.g. http://localhost:11434)

Complete example config

{
  "workspace": "~/.human/workspace",
  "default_provider": "openai",
  "default_model": "gpt-4o",
  "default_temperature": 0.7,
  "providers": [
    {
      "name": "openai",
      "api_key": "sk-your-openai-key",
      "base_url": null,
      "native_tools": true
    },
    {
      "name": "anthropic",
      "api_key": "sk-ant-your-anthropic-key"
    },
    {
      "name": "ollama",
      "api_key": null,
      "base_url": "http://localhost:11434"
    }
  ],
  "channels": {
    "cli": true,
    "default_channel": "cli",
    "email": {
      "smtp_host": "smtp.gmail.com",
      "smtp_port": 587,
      "from_address": "bot@example.com",
      "smtp_user": "bot@example.com",
      "smtp_pass": "app-password",
      "imap_host": "imap.gmail.com",
      "imap_port": 993
    },
    "imessage": {
      "default_target": "+15551234567"
    }
  },
  "memory": {
    "backend": "sqlite",
    "auto_save": true,
    "sqlite_path": null,
    "max_entries": 0
  },
  "security": {
    "sandbox": "auto",
    "autonomy_level": 1
  },
  "autonomy": {
    "level": "supervised",
    "workspace_only": true,
    "max_actions_per_hour": 20
  },
  "gateway": {
    "enabled": true,
    "port": 3000,
    "host": "127.0.0.1",
    "require_pairing": true,
    "allow_public_bind": false,
    "pair_rate_limit_per_minute": 10,
    "webhook_hmac_secret": null
  },
  "tunnel": {
    "provider": "none",
    "domain": null
  },
  "runtime": {
    "kind": "native",
    "docker_image": null
  },
  "tools": {
    "shell_timeout_secs": 60,
    "shell_max_output_bytes": 1048576,
    "web_fetch_max_chars": 100000,
    "enabled_tools": [],
    "disabled_tools": []
  },
  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    }
  },
  "cron": {
    "enabled": true,
    "interval_minutes": 1
  }
}

Provider config

Each entry in the providers array can have:

| Field | Type | Description | | -------------- | ------- | ------------------------------------------------------------------------------------------------------------------ | | name | string | Provider identifier: openai, anthropic, ollama, llamacpp, lmstudio, vllm, sglang, openrouter, etc. | | api_key | string | API key (optional for local providers) | | base_url | string | Override base URL (e.g. http://localhost:11434 for Ollama) | | native_tools | boolean | Use provider-native tool format (default: true) |

Local providers (no API key required): ollama, llamacpp, llama.cpp, lmstudio, lm-studio, vllm, sglang, osaurus

Memory backends

sqlite — SQLite with FTS5 and vector search (requires HU_ENABLE_SQLITE)
markdown — File-based markdown files
none — No memory

Tool filtering

Use enabled_tools and disabled_tools to control which tools are available:

{
  "tools": {
    "enabled_tools": ["shell", "file_read", "memory_store"],
    "disabled_tools": ["browser_open"]
  }
}

Empty enabled_tools means all tools are enabled unless listed in disabled_tools.

MCP Servers

Connect to external MCP (Model Context Protocol) servers. Human can act as both client and server:

As client — connect to external tool servers at startup:

{
  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

MCP tools are automatically loaded and available to the agent as mcp_0_<tool_name>.

As server — expose all Human tools over MCP:

human mcp

This runs the JSON-RPC 2.0 server on stdin/stdout, compatible with Claude Code and other MCP clients.

Service Mode

Run Human as an always-on service:

human service          # Daemonize (background)
human service-loop     # Foreground (for containers)
human status           # Check if running

The service loop executes cron jobs and will poll configured channels in future releases.