Architecture Deep Dive
How Botsters Works
Four hard questions about AI agent security — answered directly.
How can agents get work done without being able to see any auth?
Two complementary mechanisms: seksh (the secure shell) and agent-tools (capability-based CLI wrappers). Both ensure that real credentials are injected at the last possible moment — inside the tool, not in the agent's environment.
seksh — AST-level secret injection
seksh is a fork of Nushell with broker-aware secret management built into the language runtime. Secrets are injected directly into the Abstract Syntax Tree at parse time — they never exist as string values in the shell environment.
This works like prepared statements in SQL. When a database driver processes
SELECT * FROM users WHERE id = ?, the user input is bound inside the
driver — it never gets concatenated into raw SQL where it could be read or escaped.
seksh works the same way: the secret is bound inside the AST, not interpolated
into a string the shell can read.
The consequence is that even explicit extraction attempts fail safely:
# Attempting to echo a secret — seksh returns a placeholder, not the value
> echo (getsek MY_OAUTH_TOKEN)
<secret:MY_OAUTH_TOKEN>
# The secret is usable, but not readable
> seksh-http get https://api.github.com/user --auth-bearer MY_OAUTH_TOKEN
# → authenticated request succeeds, token never appears in outputAn agent operating under prompt injection, or one explicitly instructed to exfiltrate credentials, encounters a dead end. The value isn't there to steal.
agent-tools — capability-scoped wrappers
agent-tools is a suite of CLI tools that wrap common authenticated operations. Agents invoke them by capability name — the Spine resolves the actual credentials and enforces what the call is allowed to do.
🌐 agent-http
HTTP client with broker-injected auth. Supports bearer tokens, basic auth, and capability-based resolution.
agent-http get \
https://api.github.com/user \
--auth-bearer github/pat🔀 agent-git
git wrapper that injects credentials into HTTPS URLs at execution time. No tokens in shell history.
agent-git clone \
https://github.com/org/repo \
--auth-token github/pat🎯 do-agent
Capability-first interface. Agents request provider actions by name; the Spine handles auth and routing.
do-agent github \
list-repos \
--org myorg📋 listagent
Lists available secrets and capabilities by name — never by value. Agents can discover what they have access to without ever seeing the underlying credentials.
listagent --capabilities
# → github/read, github/write, cloudflare/deploy, hetzner/dns ...Capability scoping — knowing what goes in and out
Because agent-tools wrap known API surfaces, the Spine understands the schema of every call. It knows what parameters are valid inputs and what a legitimate response looks like. This enables two things standard shell access cannot provide:
- Inbound scoping: Credentials are only injected into calls that
match the registered capability. An agent with
github/readcannot use that grant to authenticate a write operation — the Spine rejects the mismatch before the call goes out. - Outbound scrubbing: Because the Spine knows what a valid API response looks like, it can detect and redact any credential values that appear in return data — catching cases where an API accidentally echoes auth material back in an error message or header.
Why does the Spine guarantee logging and attestation?
Both inference and actuator actions.
In a standard agent setup, logging is optional — an afterthought bolted on by whoever built the integration. The agent might log. Or it might not. When something goes wrong, you're reconstructing what happened from fragments.
The Spine makes logging structurally mandatory, not a configuration choice.
Why "guaranteed" isn't just a claim
Every outbound call — inference requests to Claude/GPT/Gemini, tool calls, shell commands, file operations, API calls to external services — flows through the Spine. There is no bypass. An agent that wants to do anything has to go through the Spine, and the Spine logs everything before dispatching.
📝 Inference Logging
Every model call is logged: timestamp, agent identity, model used, token counts, and response hash. The Spine proxies all inference traffic — there is no path for an agent to call a model without leaving a record.
This also enables cost attribution across a multi-agent system — you know exactly which agent spent how much.
⚙️ Actuator Action Logging
Every task dispatched to an Actuator — shell command, file write, git operation, browser action — is logged before execution, with the requesting agent's identity attached.
The Actuator cannot receive a task without the Spine having recorded it first. Execution and logging are not separable steps.
Attestation of where the agent is running
The Spine doesn't just log what an agent does — it attests to where it's running. Each Brain connects to the Spine through a registered identity, and the Spine verifies that identity on every session. An agent cannot silently migrate to a different host, clone itself to a new environment, or operate outside its registered Actuator — because without the Spine connection, it literally cannot think.
Unlike a standard OpenClaw setup, a Botsters Brain cannot abscond with its OAuth token or API key for inference. The inference credentials live in the Spine. A Brain that loses its Spine connection loses the ability to call any model at all. There is no "offline mode" that preserves access — the connection to the Spine is the access.
Attestation: knowing logs haven't been tampered with
Logging is only useful if you can trust the logs. The Spine provides attestation by being the sole authorized intermediary — neither Brains nor Actuators write directly to the log store. An agent cannot delete or alter its own log entries because it has no interface to do so. Log integrity is enforced by access architecture, not by trusting the agents themselves.
The comparison
Why is Brain/Spine/Actuator superior to standard OpenClaw?
OpenClaw is excellent software — the Botsters Brain is built on an OpenClaw fork. This isn't a criticism of OpenClaw. It's an observation that OpenClaw is designed for a different threat model: a trusted operator running an agent on trusted infrastructure with well-understood tool access.
That assumption breaks down when agents operate autonomously for extended periods, process untrusted input, share infrastructure with other agents, or run in contexts where you need to audit behavior after the fact.
The architectural difference
Standard OpenClaw
- Single trust boundary
- Credentials in agent environment
- Agent can log — or not
- All capabilities always available
- Compromise = full access to secrets and tools
Brain / Spine / Actuator
- Three distinct trust boundaries
- Credentials isolated in Spine vault
- Logging mandatory by structure
- Capabilities scoped per actuator
- Compromise of Brain yields no secrets
Separation of concerns — for real
In the BSA model, the Brain decides but doesn't execute. The Actuator executes but doesn't reason. The Spine mediates — handling credentials, routing, logging, and policy enforcement. Each layer does one thing and is auditable in isolation.
This also means each layer can evolve independently. You can swap the Brain for a different model provider, update the Actuator runtime, or harden the Spine's credential handling — without touching the other layers.
Capability scoping
Each Actuator registers the capabilities it supports: shell,
git, browser, file-system, and so on.
The Brain requests tasks by capability. The Spine routes to a matched Actuator
and enforces that the task matches the registered capability profile.
A Brain that should only do code review cannot run shell commands if no
shell-capable Actuator is registered for it. The constraint is
structural — you're not relying on the agent to remember what it's not supposed to do.
Capability scoping also applies to API calls made through agent-tools. Because the Spine knows the schema of each registered capability, it knows what parameters are valid inputs and what a legitimate response looks like. Credentials are only injected into calls that match the capability's definition — and responses are scrubbed against the same schema before being returned to the agent.
Why not just firewall or sandbox OpenClaw?
Standard OpenClaw has a fundamental structural problem that a firewall cannot fix: the attack surface and the secrets share the same boundary. The agent processes untrusted input and holds credentials in the same environment. A firewall controls where traffic goes — it does nothing about what's already inside.
BSA eliminates this by separating the attack surface from the secrets entirely. The Brain — which processes untrusted content, executes tools, and is the most exposed layer — never holds credentials. The secrets live in the Spine, which the Brain cannot directly access. A successful attack on the Brain yields nothing it can use to escalate.
The other problem: who controls the firewall?
A firewall or sandboxing product for OpenClaw agents poses a dilemma that has no good answer within that architecture:
🏢 On-premise firewall product
You're running third-party security software in your own data center. That software has visibility into your agents' inference traffic, tool calls, and potentially the credentials your agents hold. You're trusting a vendor's product with your most sensitive agent activity — and it's running inside your perimeter.
☁️ Cloud-based proxy / CASB
All of your AI agent inference data — every prompt, every tool call, every response — leaves your network and transits through a third party's infrastructure. You've traded one security problem (unsandboxed agents) for another (sensitive inference data leaving the company firewall).
With Botsters, the customer controls the Spine. The Spine is deployable in your own infrastructure — your data center, your VPC, your rules. It holds all secrets, all logging, all attestation. Nothing about your agents' behavior has to transit a third-party network. The security product isn't a vendor black box sitting in your environment — it's your own infrastructure, built on open software.
What a firewall specifically cannot do
❌ Identity
A firewall sees traffic to api.github.com. It doesn't know
whether that request came from your coding agent following instructions,
or a compromised agent exfiltrating repository contents via prompt injection.
❌ Credential Containment
A firewall doesn't prevent an agent from reading credentials that are already in its environment and encoding them in a permitted outbound request — to a whitelisted domain, in a query parameter, in a JSON body. Exfiltration within allowed destinations is invisible to a network filter.
❌ Semantic Logging
Firewall logs record connections: source, destination, bytes. They don't record that the agent deleted a file, committed to main, or made a 50,000-token inference call. Agent behavior cannot be reconstructed from network logs alone.
❌ Fine-Grained Revocation
To stop a compromised agent at the network level, you block its IP — which blocks everything on that host. The Spine revokes a single agent token in milliseconds, without affecting any other agent or service.
Defense in depth
Firewalls and the Spine aren't alternatives — they're complementary. A firewall is a good perimeter control that prevents agents from reaching destinations they should never reach. The Spine covers what a firewall cannot:
- Network layer: Firewall + egress allowlist — stops obvious bad destinations
- Application layer: Spine — identity, credentials, logging, revocation, owned by you
- Execution layer: Actuator capability scoping — limits what agents can do structurally
- Content layer: Output scrubbing — catches credentials in responses
A firewall alone covers one of these four layers. BSA covers the other three — and does so on infrastructure you control, with no third-party visibility into your agents' inference traffic.
Ready to go deeper?
The architecture is open. Read the docs, explore the code, or get in touch.