agent.sh: an LLM agent in busybox
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.

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:
shell(command)— always present. Runs a command under the execution shell and returns combined stdout/stderr, truncated.skill(name)— present when the workdir has.agents/skills/<name>/SKILL.mdfiles. Loads a skill’s text (the Agent Skills convention); the skill list goes into the system prompt.delegate(task, timeout?)— present whenAGENT_SELFis set. Spawns a nestedagent.shfor a sub-task; the child’s final answer is the tool result. Depth-limited, so a child can’t delegate further.mcp_<server>_<tool>— present when MCP servers are configured. Each server’s tools are exposed under its advertised name.
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:
- Workspace instructions. If the workdir has an
AGENTS.md, it is appended to the system prompt.-wsets the workdir; the agentcds into it and tells the model it is the place to write. - Model parameters.
-P key=value(repeatable) adds fields to the request body, e.g.-P temperature=0.7 -P enable_thinking=true. Values are numbers,true/false/null, raw JSON, or strings. - Sub-agents. Set
AGENT_SELFto the path or URL ofagent.shand the model can calldelegateto hand off a self-contained sub-task.-dsets how many levels deep that can go (default 1).
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:
- In-memory request/response. The request and response live in shell variables — no
mktemp, no temp files, nothing on disk. That is what lets it run on a read-only root or a target without/tmp. busybox wgetis the HTTP client. GNU wget can’t read a request body from a pipe, so the body is piped in via--post-file=/dev/stdin. The same client serves both the model endpoint and MCP, so there is one transport path.- Every option has an
AGENT_*env default. The script runs with no arguments at all — set the environment and pipe the file in. That is the intendedwget | ash -s -usage:
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:
- Env scrubbing — every model command runs with the full
AGENT_*set removed (key, task, workdir, …), so a prompt-injected command can’t read them casually. This is not a security boundary; a same-user process can still read/proc/$PPID/environ. - Per-command timeout — the command runs in its own session (
setsid); on expiry the whole process group is killed, not just the shell. - Output truncation — each tool result is capped in bytes (16 KB by default), so a runaway
lscan’t flood the context. - Model-request timeout — a hung model request is cut off after a fixed silence (
-H, default 300 s). --ask— confirm each command before it runs (y/n/q). Off by default.
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:
- JSON parsing is slow. The vendored
json.shwalks a document one character at a time in shell, so very large responses (big file dumps, long MCP tool lists) take noticeable time. - No context management. The whole history is re-sent every turn and the tool loop is unlimited by default. Use
-tto cap it on long tasks. - Tools run one at a time, in order, even if the model asks for several at once.
- The API key is visible to same-user processes. It sits in
wget’s arguments, so run the agent in a sandbox with a private/proc.
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:
- github.com/meefik/agent.sh — MIT, single file
Stack: busybox ash, busybox wget, OpenAI tools protocol, MCP (Streamable HTTP)
Comments