Standalone CLI agents for the SuperInstance distributed ecosystem. Download, onboard, and orchestrate. Every agent tells its story in commits.
┌──────────────────────────────────────────────────────────────────────┐
│ SUPERINSTANCE │
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Agent │ │ Agent │ │ Agent │ │ Agent │ │
│ │ (any) │ │ (any) │ │ (any) │ │ (any) │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │
│ └───────────────┼───────────────┼───────────────┘ │
│ │ │ │
│ ┌─────────▼───────────────▼─────────┐ │
│ │ MESSAGE BUS │ │
│ └─────────┬───────────────┬─────────┘ │
│ │ │ │
│ ┌───────────────┼───────────────┼───────────────┐ │
│ │ │ │ │ │
│ ┌────▼─────┐ ┌────▼─────┐ ┌────▼─────┐ ┌────▼─────┐ │
│ │ KEEPER │ │ GIT-AGENT│ │ ORACLE │ │ DATUM │ │
│ │ │ │ │ │ │ │ │ │
│ │ Secrets │ │ Workshop │ │ Task │ │ Audit │ │
│ │ Boundary │ │ Repo │ │ Dispatch │ │ Analysis │ │
│ │ Registry │ │ Inventory│ │ Discovery│ │ Journal │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ═════════════ BOUNDARY ENFORCEMENT ═════════════ │
│ Secrets NEVER leave the SuperInstance network boundary │
│ │
└──────────────────────────────────────────────────────────────────────┘
pip install click rich toml
# Optional but recommended: pip install cryptography # AES-256 encrypted secretsKEEPER_PASSWORD=your-master-password python bin/keeper serve --port 7742python bin/git-agent init --workshop ./my-workshop --owner my-agentpython bin/git-agent --workshop ./my-workshop onboard
python bin/oracle --workshop ./my-workshop onboard
python bin/datum --workshop ./my-workshop onboard# While the Keeper is running:
python bin/keeper add-secret github_pat ghp_xxxx --description "GitHub PAT"
python bin/keeper add-secret openai_api_key sk-xxxx --description "OpenAI API key"
python bin/keeper list-secretspython bin/oracle --workshop ./my-workshop add "Build JSON parser" --priority high --cap python
python bin/oracle --workshop ./my-workshop board
python bin/oracle --workshop ./my-workshop auto-dispatchpython bin/git-agent --workshop ./my-workshop commit -m "feat: add JSON parser" --reasoning "Needed for config file processing"
python bin/git-agent --workshop ./my-workshop smart-commit "Fixed off-by-one in array indexing" "Found during testing"
python bin/git-agent --workshop ./my-workshop historypython bin/datum --workshop ./my-workshop audit
python bin/datum --workshop ./my-workshop analyze
python bin/datum --workshop ./my-workshop journal "DISCOVERY" "Found performance issue in loop"| Agent | Role | CLI | Key Capabilities |
|---|---|---|---|
| Keeper | Secret holder & boundary enforcer | python bin/keeper |
AES-256-GCM encryption, boundary enforcement, audit logging, agent registry, HTTP API |
| Git-Agent | Workshop operator & commit historian | python bin/git-agent |
Smart commits, workshop init from template, tool/recipe inventory, branch management |
| Oracle | Fleet coordinator & task dispatcher | python bin/oracle |
Task board (TASKBOARD.md), fleet discovery, capability matching, priority management |
| Datum | Research & analysis specialist | python bin/datum |
Workshop audit, conformance testing, cross-repo analysis, journal management |
A repo IS a workshop. Every agent operates through a workshop — a git repo that fills with tools, scripts, interpreters, and custom compilers over time.
workshop/
├── bootcamp/ ← Training area for new agents
├── dojo/ ← Advanced skill-building and kata
├── tools/ ← Scripts, interpreters, compilers
│ └── manifest.json ← Tool registry
├── recipes/ ← Saved command sequences for recurring tasks
├── wiki/ ← Knowledge base and documentation
├── .superagent/ ← Agent configuration
│ └── agent.toml
├── TASKBOARD.md ← Task tracking (human-readable + machine-parseable)
└── JOURNAL.md ← Chronological work journal
| Level | Languages | Purpose |
|---|---|---|
| Low | C, Rust, Zig | Custom interpreters and compilers — just-so for the application |
| Mid | Python, Bash | Tools and automation — rapid development |
| High | Python, JSON, TypeScript | Iteration, parsing, filter-prompting — maximum flexibility |
Over time, workshops accumulate custom compilers that reduce low-level reasoning. The agent thinks less about mechanics and more about the problem.
The Keeper is the sole holder of secrets. No other agent ever stores a secret.
Agent needs GitHub token
│
▼
SecretProxy.request_secret("github_pat", "push commits to repo")
│
▼
Keeper receives request:
1. Verify agent is registered
2. Check purpose is stated
3. Boundary check — is destination internal?
4. Look up secret in encrypted store
5. Audit the access
6. Return value (or deny with reason)
│
▼
Agent uses token for git push (never stores it)
- Secrets may only be used for requests to internal SuperInstance hosts
- Blocked patterns: pastebin.com, public gists, discord webhooks, etc.
- Every access is logged with requester, purpose, timestamp, approved/denied
- Fail-closed: unknown destinations are denied by default
- TTL-limited: secrets have a maximum lifetime per request (3600s)
Every agent supports onboard to join the fleet:
Step 1: Configure → name, role, capabilities, keeper URL
Step 2: Keeper → handshake + registration
Step 3: Workshop → initialize from template (bootcamp/dojo/tools/wiki/recipes)
Step 4: Config Save → write .superagent/agent.toml
Step 5: Activate → agent goes ACTIVE, starts listening on message bus
Agents can also run in standalone mode if no Keeper is reachable — they'll fall back to environment variables for secrets (with a warning that access is unaudited).
Agents communicate through the MessageBus:
- In-process: Direct pub/sub within a single machine
- TCP: Cross-machine communication (port 7743 by default)
- Message types: TASK, STATUS, QUERY, RESPONSE, ALERT, HEARTBEAT
- Messages are JSON, persisted to
.superagent/bus.json
from superagent.core import Agent, AgentConfig
from superagent.keeper import KeeperAgent
from superagent.git_agent import GitAgent
from superagent.oracle import OracleAgent
from superagent.datum import DatumAgent
# Create a thinking agent
class MyAgent(Agent):
role = "researcher"
def run(self, **kwargs):
self.activate()
# Do work...
# Onboard
agent = MyAgent(config=AgentConfig(name="alice", role="researcher"))
agent.onboard("http://localhost:7742")
# Request a secret (proxied through Keeper)
token = agent.proxy.github_token("push commits")MIT