Skip to main content

Build on Codebolt

This section is for developers extending Codebolt. If you want to use Codebolt, start at Using Codebolt. If you want to follow a specific how-to, try Guides. Everything here is for people writing code that plugs into the server.

If you are new to the builder-facing architecture, read Architecture for Builders first. It explains how the server, clients, agents, plugins, and agent extensions fit together.

The system at a glance​

The Codebolt server is the execution engine. It owns files, memory, sub-agents, tool execution, the event log, guardrails — everything stateful. Around it, four external surfaces let you build on top without forking the server. Inside it, a handful of internal extension points let you reshape the agent loop without rewriting it.

Codebolt system architecture — server and extension surfacesws · http routesplugin bus · wscodeboltjs · wsprovider proxy · wsCODEBOLT SERVERexecution engineEVENT LOGMEMORYCONTEXTTOOLS / MCPSUBAGENTSLLM / EMBSHADOW GITGUARDRAILSextend internallyskills · processors · agent blocks · memory layoutCUSTOM UIsclientsdk · chat widgets · cliCUSTOM AGENTScodeboltjs+ vercel ai sdk · langchainPLUGINSpluginSdkhooks · ui ext · capabilitiesREMOTE ENVIRONMENTPROVIDERSe2b · k8s · ssh · llm · embprotocol / bustrafficinternal subsystem
  • Custom Interfaces — build your own chat panel, CLI, or editor extension using the clientsdk, a wrapper over the server's WebSocket protocol and HTTP routes.
  • Custom Agents — write agents with codeboltjs, or bring your own framework (Vercel AI SDK, LangChain) via the adapter layer. Agents drive the server over WebSocket.
  • Plugins — extend the application itself with the pluginSdk: gateway integrations, execution plugins, UI extensions, hooks, and custom LLM providers. Plugins live alongside the server and talk to it over the plugin bus.
  • Remote Environment Providers — federate across machines. A remote environment provider is typically another Codebolt server instance (e.g. e2b, a remote sandbox, or a peer workstation) that the local server proxies work to.

Inside the server, you can also extend the agent loop without rewriting it — capabilities, skills, action blocks, agent blocks, and more are all configurable from the same .codebolt/ project surface. See Agent Extensions.

The extension surface at a glance​

Codebolt exposes these extension points. Agent customization now splits into two top-level sections: create a new agent, or extend existing agents without rewriting them.

Extension pointWhat it isStart here
Architecture for BuildersThe server-centered mental model and SDK splitArchitecture for Builders
Creating AgentsWrite or wrap agents that show up in the pickerCreating Agents
Agent ExtensionsShared primitives agents consume: skills, capabilities, MCP tools, and blocksAgent Extensions
Custom InterfacesBuild your own interface on top of the serverCustom Interfaces
PluginsExtend the application runtime — gateways, execution plugins, UI panels, hooks, providersPlugins
Remote Environment ProvidersLLM, embedding, or remote execution backendsRemote Environment Providers
Evaluation & OptimizationMeasure, refine, and tune agentsEvaluation & Optimization
Multi-Agent OrchestrationMulti-agent coordination design — swarms, flows, roles, and review patterns.Multi-Agent Orchestration
Multi-Environment OrchestrationProvider-driven execution across remote or alternate environments.Multi-Environment Orchestration
InternalsHow the server works — for devs who need to extend intelligently.Internals

Plus Self-Hosting for teams running the server themselves and Remote Execution for distributed agent runs.

Which one do I need?​

A decision guide:

The level-zero mindset​

Codebolt is designed so you almost never need to modify it to get what you want. The extension points, in order of effort:

  1. Configuration. .codebolt/ files in your project: rules, context rules, hook definitions, flow graphs. Often enough for real use cases. No code at all.
  2. Install an MCP server or capability. Every agent in the project gains new tools / behaviour. See Agent Extensions.
  3. Remix an existing agent. Change its prompt, tools, or model without forking its code. See Level 0 — Remix.
  4. Write a plugin. Extend one part of the application without forking the server. See Plugins.
  5. Build a skill or action block. Reusable competency any agent can call. See Skills.
  6. Build an MCP server. Give agents new capabilities. Usually a small standalone program.
  7. Build a custom agent from the framework. Full control over the loop but with batteries included. See Level 1 — Framework.
  8. Build on codeboltjs directly. Everything the framework gives you and nothing you don't want. Level 2.
  9. Write against the raw WebSocket protocol. Only if you need something no level above allows. Level 3.

Start at the top and stop as soon as you have what you need. Most extensions live at level 1-6.

Writing for agents vs writing for humans​

One mental shift to make early: the code you write in Build is consumed by an LLM in addition to (or instead of) humans. That changes what "good" means:

  • Tool descriptions matter more than doc comments. An LLM chooses which tool to call based on its description. A vague description means wrong tool choices.
  • Error messages are data for a reasoning loop. "Failed to read file" is useless; "Failed to read file: path does not exist, nearest matches: …" lets the agent recover.
  • Schemas are contracts with the LLM. If your tool takes { path: string } but the agent keeps passing { file: string }, your schema is the bug, not the agent.
  • Idempotency is a feature. Agents retry. Tools that are safe to call twice are better than tools that aren't.

These aren't rules, just things to keep in mind as you write.

See also​