Meefik's Blog

Freedom and Open Source

agent.sh: an LLM agent in busybox

17 Nov 2026 | ai linux shell

Most LLM agent harnesses assume a normal machine: a Python or Node runtime, a package manager, a writable /tmp. None of that exists on the devices I actually care about — an ARM board with a read-only root, an embedded target where the only thing in /bin is busybox. I wanted an LLM agent that still works there.

So I wrote agent.sh: a single-file LLM agent in ash (busybox’s POSIX shell). One executable, only busybox applets — no jq, no python, no curl. It speaks the OpenAI tools protocol natively: the model asks for a tool, the harness runs it, feeds the result back, and loops until the model answers in plain text.

The agent.sh tool loop: model → tool call (shell, skill, delegate, mcp) → harness runs it → result back, looping until the model answers in plain text. Badges: only busybox applets, no jq/python/curl, read-only root OK.

What it runs against

It points at any OpenAI-compatible /v1/chat/completions endpoint and takes a task. The defaults are a local Ollama on http://localhost:11434/v1, model qwen3, no key — so you can just pass the task:

busybox ash agent.sh "What is today's date?"

To change the endpoint, model, or key, use the -e, -m, -k flags (or the AGENT_ENDPOINT, AGENT_MODEL, AGENT_KEY environment variables):

AGENT_ENDPOINT="https://api.openai.com/v1" AGENT_KEY="sk-..." AGENT_MODEL="gpt-4o-mini" \
    busybox ash agent.sh "What is today's date? Use the 'date' command to find out."

The model’s commands run as plain children of the harness, and the final answer prints to stdout. There is no UI, no daemon, no state directory.

The tools

The model gets a small set of native tools:

The agent loop is the whole thing: POST the messages and the tool list, and if the response carries tool_calls, run each one (one at a time, in order), append the result, and loop. When the response has no tool calls, the content is the final answer.

A run looks roughly like this (diagnostics go to stderr, the answer to stdout):

$ busybox ash agent.sh "What is today's date?"
[agent] workdir: /root
[agent] turn 1
[agent] tool shell: date
[agent] turn 2
Today is Wednesday, 18 November 2026.

Streaming

By default the agent is silent until the final answer. Add -S (or AGENT_STREAM=1) to watch the model work live:

busybox ash agent.sh -S "What is today's date? Use the 'date' command to find out."

The request is sent with stream: true, and the SSE response is read line by line as it arrives. Content tokens go to stderr as they come in; for reasoning models (Qwen3, DeepSeek, …), the chain of thought is shown too, prefixed with [thinking]. Tool-call fragments (id, name, arguments in pieces) are accumulated by index. When the stream ends, the harness reassembles it into a normal non-streamed response, so the rest of the loop is unchanged. The final answer still goes to stdout, so piping and scripting keep working.

The stream is parsed in the shell with the same vendored JSON parser and kept in memory, so it still needs no temp files. Delegated sub-agents inherit the setting, so you see their progress as well. In a terminal the answer shows up twice, once streamed and once on stdout, because stdout is kept clean for scripts.

Skills, sub-agents and parameters

A few options make the agent more useful without changing its shape:

AGENT_SELF=./agent.sh busybox ash agent.sh -P temperature=0.2 \
    "Summarize every *.log file in /var/log, one sub-agent per file"

The embedded constraint

The busybox-only rule is the whole point, and it shapes the design:

AGENT_TASK="..." busybox wget -qO - https://github.com/meefik/agent.sh/raw/main/agent.sh | busybox ash -s -

Or pipe the task in on stdin:

cat task.md | busybox ash agent.sh

Safety

There is no sandbox of its own — wrap the script in whatever sandbox you want (podman, bwrap, unshare, firejail). What the harness adds are the layers that don’t depend on a sandbox:

MCP without curl

MCP speaks JSON-RPC over HTTP. agent.sh connects a server with -M name=url over Streamable HTTP using busybox wget (no curl), so it works on minimal embedded targets where npx, python, and node are absent. The Mcp-Session-Id header is read via wget -S and sent back, so stateful servers work. A broken server warns and is skipped — it never breaks the agent.

Limitations

The busybox-only rule has a price:

Tests

The test suite runs the real functions extracted from agent.sh, plus integration tests that run the whole agent against pure-busybox mock endpoints — no python. The mocks double as proof of the embedded constraint: they run on the target shell with nothing but busybox applets.

busybox ash tests/run_tests.sh

Wrap up

The goal was an LLM agent that survives a machine with nothing but busybox — one file, no runtime, no writable disk, native tool calling. If you want an agent that runs on an embedded target or a read-only root:

Stack: busybox ash, busybox wget, OpenAI tools protocol, MCP (Streamable HTTP)

Comments