A minimal FSM-based core for building fast, controlled agents for OrcAI.
Whitebox is not a standalone assistant.
It is a runtime designed to work as an execution unit inside the OrcAI orchestration system.
Whitebox is a lightweight agent core built around an FSM orchestrator.
It is designed to:
- execute tasks received from OrcAI
- keep behavior predictable
- avoid hidden complexity
Each instance acts as a worker that processes tasks of a specific type.
In orchestration systems, the main issue is not intelligence, but control.
Typical agents:
- accumulate uncontrolled context
- mix responsibilities
- behave inconsistently
- consume unpredictable tokens
Result:
- high API cost
- unstable execution
- hard-to-debug pipelines
Whitebox is designed for OrcAI’s model:
- tasks come from a broker (
task.created) - agents are stateless workers
- behavior is strictly controlled
Key principles:
- explicit context only
- no hidden injections
- deterministic execution
The only built-in injection is the output protocol.
Context is simple and file-based.
~/.whitebox-name/
context/
minds/
memories/
skills/
tools/
sessions/
workspace/
How it works:
- all files in
context/are loaded into the prompt - nothing outside this directory exists for the model
- no implicit memory or hidden layers
This ensures:
- predictable inputs
- stable outputs
- controlled token usage
Context is fully owned by the system.
The only built-in rule is a strict LLM output protocol.
The model must respond in valid JSON:
{
"type": "tool",
"tool": "bash",
"arguments": {
"command": "git status"
}
}or
{
"type": "final",
"answer": "task completed"
}This protocol is used by the engine to:
- parse model output deterministically
- decide whether to execute a tool or finish
- keep execution predictable
It is not related to OrcAI routing. OrcAI operates on task/event level, while this protocol is strictly between the LLM and the local engine.
States:
- Idle
- DoOne
- DoSecond
- Final
- Fail
No planning. No hidden reasoning.
Execution loop:
- receives task input
- calls LLM
- parses JSON
- executes tool
- publishes results back
Integrated with broker:
- consumes
task.created - emits
task.logs,task.result,task.error
Minimal runtime state:
- goal
- last result
No persistent memory by default.
Whitebox is optimized for orchestration workloads.
- written in Go
- low memory usage
- fast startup and execution
- no background overhead
Strict context control reduces token usage and cost.
Built-in support for Langfuse:
- full trace per task
- LLM inputs and outputs
- token usage
- execution steps
This makes every task observable inside OrcAI.
- FSM-based execution worker
- strict tool/final protocol
- explicit context control
- NATS-compatible task processing
- low resource usage
- predictable behavior
Whitebox is used inside OrcAI to run agents.
Each agent:
- subscribes to
task.created.* - filters by
type - processes only its tasks
- publishes results back
Typical usage:
- git agents
- file system agents
- code execution agents
- domain-specific workers
Whitebox is a “blaze agent” core for OrcAI:
- fast
- minimal
- controllable
- cheap to run
It is designed for execution, not autonomy.
git clone https://github.com/Alice088/whitebox.git
cd whitebox
go mod downloadcp .env.example .envgo run .- execution over reasoning
- control over automation
- explicit over implicit
- simple over complex