nodetool agent run runs one CodeAct turn: the objective is the user message, the model acts by writing sandboxed JavaScript over the toolbelt (the same loop the chat runs), and the final answer prints to stdout. A live trace of tool calls, plan events, and task events streams to stderr. There is no configuration file.
Subcommands
nodetool agent run --objective "..." # run the agent loop
nodetool agent diagnose <job_id> # aggregate a failed run into one report
nodetool agent run
nodetool agent run -p anthropic -m claude-sonnet-5 \
--objective "Research the latest AI trends"
echo "Research the latest AI trends" | \
nodetool agent run -p anthropic -m claude-sonnet-5
Options:
-o, --objective <text>— Objective for the agent. Without it, read from piped stdin-p, --provider <id>— Provider id (required)-m, --model <id>— Model id (required)-w, --workspace <path>— Workspace dir for file tools (default: cwd)--max-iterations <n>— Tool-calling rounds in the turn (default 25)--permission-mode <default|auto|plan>— How tool calls are gated (see Permission mode)--cost-cap <usd>— Ceiling on provider spend for the whole run;0lifts it--timeout <s>— Wall-clock bound on the run in seconds;0gives the run no time, so it stops before its first model call--json— Emit each agent event as a JSON line on stderr-v, --verbose— Include low-level chunk and other events in the trace
Run budget
--cost-cap and --timeout override two of the five NODETOOL_AGENT_*
settings a chat turn reads (NODETOOL_AGENT_TURN_COST_CAP_USD,
NODETOOL_AGENT_TURN_DEADLINE_MS); concurrency, total turns, and the
unpriced-token ceiling come from the settings alone.
The run holds one budget and shares it downward — a sub-agent, an
execute_plan DAG, an AgentNode reached through run_node — so the ceiling
bounds the run, not each loop. A cap is admission: a turn whose worst case
would cross it is refused before the call, not noticed after the money is
spent. A model with no catalog price has no worst case and is admitted against
a prompt-token ceiling instead, never as free.
A ceiling that stops the run prints its reason and exits non-zero
(agent stopped: turn budget of $0.01 reached); with --json the same reason
arrives as an error event. Every run ends with what it committed —
spent $0.0123.
nodetool agent run -p openai -m gpt-5.4-mini -o "Research AI trends" \
--cost-cap 0.50 --timeout 120
Permission mode
The modes are defined in the CLI reference. An
unrecognized value is an error. With a terminal on stdin, the default mode is default. The prompt goes to
stderr and takes y (this call), n (refuse), or a (this tool for the rest
of the run). When the objective arrives down a pipe nobody can answer, so the
run uses the headless gate (auto), prints a notice once, and denies anything
the gate escalates. An explicit --permission-mode still applies. With
--json the notice and any prompt arrive as log_update events.
Tools
The agent gets the default toolbelt: files, search, browser, PDF, vision,
critique, memory, assets, todo, plus the platform tools — workflows,
nodes, jobs, apps, models, and media generation. This is the same belt the chat
agent and the MCP bridge assemble, so the surfaces cannot drift. The belt is not
narrowable from the command line — nodetool agent run has no --tools flag.
The belt is assembled by buildCliAgentBelt, shared with the CLI’s own chat,
and carries the capabilities that spawn loops of their own: run_subtask,
start_subtask, wait_subtasks, run_search, and — here, unlike chat — both
create_plan and execute_plan. The provider itself is offered execute_code
plus the direct tools; the rest of the belt lives in the sandbox.
What the planner used to do
The model calls create_plan when the objective wants decomposing, and execute_plan runs that DAG. The permission gate on execute_plan is the plan approval. There are no flags for checkpoints, the plan cache, separate planning and reasoning models, or skill auto-selection, which the model does itself with load_skill. --max-iterations bounds tool-calling rounds in the turn.
nodetool agent diagnose
Aggregates a failed run — the failing node or step, its error, the last LLM call, and the agent’s memory — into one report.
nodetool agent diagnose <job_id>
nodetool agent diagnose <job_id> --json
nodetool agent diagnose <job_id> --trace-file trace.jsonl
Messages and spans come from a debug bundle in nodetool-debug/<job_id>-*/
when one exists. --trace-file wins over NODETOOL_TRACE_FILE, which wins over
the bundle’s own trace.jsonl. --api-url points the job lookup at a remote
server.
Output
# Capture the result, discard the trace
nodetool agent run -p openai -m gpt-5.4-mini -o "Task" 2>/dev/null > result.txt
# Machine-readable event stream on stderr
nodetool agent run -p openai -m gpt-5.4-mini -o "Task" --json 2>events.jsonl
API keys
Keys come from the secret store (nodetool secrets store OPENAI_API_KEY) or the
environment:
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
Chaining runs
nodetool agent run -p anthropic -m claude-sonnet-5 \
-o "Research topic X" > research.md
nodetool agent run -p anthropic -m claude-sonnet-5 \
-o "Write an article based on: $(cat research.md)"
Related Documentation
- Chat & Agents — Agent system overview
- Chat CLI — Interactive chat interface
- NodeTool CLI — Complete CLI reference