Mini Agent

This is a maximal fork of the minimal agent by @obra -> https://github.com/obra/smallest-agent

More verbose, for the "Your AI Agent is just a while loop with an API call. Let me prove it" presentation purposes 😊 Check the slides presentation on slides.com/michalczukm/your-ai-agent-is-while-loop-short

How to use

JUST DON'T!

IT HAS UNRESTRICTED BASH ACCESS.

IT CAN DO ANYTHING.

IT MIGHT DECIDE TO ERASE ALL YOUR FILES AND INSTALL LINUX

If you'd like to run it, like I do, use Docker Sandboxes to isolate the agent in a microVM.

1. Start the sandbox (on the host) and set the envs

Copy the .env.template to .env and fill in the API keys.

npm run sandbox:run

This starts (or resumes) a sandbox for this workspace. The sandbox name is derived from the directory name — e.g. shell-smallest-agent.

2. Allow outbound traffic to the provider (on the host, once)

The sandbox proxy's default allowlist only covers Anthropic endpoints. For Mistral, run once on the host while the sandbox is running:

npm run sandbox:network

To inspect what traffic is being allowed or blocked:

npm run sandbox:log

3. Run the agent (inside the sandbox)

# clone and install inside the sandbox
git clone https://github.com/michalczukm/smallest-agent.git && cd smallest-agent
npm ci

# Anthropic
npm run start:anthropic

# Mistral / Codestral
npm run start:mistral

Network notes

• Node.js v20 native fetch does not respect HTTP_PROXY/HTTPS_PROXY env vars — the code uses undici's ProxyAgent with HTTPS_PROXY=http://host.docker.internal:3128 to route through the sandbox proxy.

Show LLM usage stats

The stats demo writes token usage data to a JSON file and lets you watch it live in a terminal UI.

Run the stats demo

Start the demo agent in one terminal:

npm run demo:stats

This writes live stats to dist/agent-stats.json.

Then start the viewer in another terminal:

npm run demo:stats-view

By default, the viewer watches dist/agent-stats.json and refreshes automatically as the file changes.

View stats from a specific file

You can also point the viewer at a specific stats file:

npm run demo:stats-view -- ./dist/agent-stats.json

For example, this is useful if you copied the stats file elsewhere and want to inspect it later:

npm run demo:stats-view -- /path/to/agent-stats.json

Example output