Tools & API keys

Built-in tools (overview)

Area	Tools (names)	External key?
Shell	`bash`	No
Files	`read_file`, `write_file`, `target_edit`	No
Search in repo	`search_tool`	No
Agents	`spawn_subagent`, `execute_task`, …	No (uses model config)
Web	`web_search`, `read_url`, `deep_research`	Serper for search
MCP	whatever your servers expose	Server-specific

Turn tools on/off:

"enabled_tools": {
  "web_search": true,
  "read_url": true,
  "deep_research": true,
  "bash": true
}

Serper (web search)

export NINJA_SERPER_API_KEY="your-serper-key"
# or
export SERPER_API_KEY="your-serper-key"

Tool	Purpose
`web_search`	Web search results
`read_url`	Fetch readable text from a URL
Researcher subagent	Multi-round search + read
`deep_research`	Several research angles in parallel

Without a key, search tools report a clear error. You can disable them in enabled_tools and use an MCP search server instead.

Keys: serper.dev.

Model API keys

These authenticate the LLM HTTP API, not tools:

export OPENAI_API_KEY="sk-..."
export NINJA_SUBAGENT_API_KEY="sk-..."   # optional

Or in config.json: openai_api_key, ninja_subagent_api_key, subagent_roles.*.api_key.

See Configure models.

MCP server keys

Put third-party tokens in the MCP server env block (or the environment of the process that starts Ninja):

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"],
      "env": {
        "MY_API_TOKEN": "..."
      }
    }
  }
}

Keep config files private (chmod 600 on Unix).

Permissions

Shell commands go through Ninja’s policy + approval prompts. Other tools (files, MCP) use confirmation and trust lists. See Approvals & safety.