README
¶
BuildMax
An open-source Agent runtime for local work and private space deployment.
Run BuildMax locally through CLI/TUI or Desktop with your own model endpoint, or deploy it for a space with centrally managed models, background workers, shared results, and governance. Both use the same Go Agent Core, so moving from one user to an organization does not mean adopting a different agent.
One Agent Core. From one developer to an entire organization.
- Try it locally — one user, one directory, no BuildMax Server required
- Run it for a space — private deployment, shared work, managed models, and background execution
- Help shape it — contribute to the runtime, local experience, enterprise platform, or trust boundaries
Status: Alpha. Interfaces, deployment guidance, and runtime behavior may change quickly before a stable release. Password sign-in and operator-assisted account recovery are available, but login is not rate limited and there is no SSO or second factor. Read docs/deploy/authentication.md before exposing a server, and CONTRIBUTING.md before contributing.
Why BuildMax
- Local without a control plane. CLI/TUI and Desktop can call your own provider, compatible gateway, or local inference endpoint. A BuildMax Server, account, and space are optional.
- Enterprise without a second agent. A private deployment adds space identity, centrally approved model aliases, workers, shared results, usage, and audit around the same runtime used locally.
- Portable by construction. The core is Go, the CLI is a single binary, models are not tied to one vendor, and tools can be extended through MCP, skills, subagents, hooks, and plugins.
The user-facing surfaces have distinct jobs:
| Surface | What it is for |
|---|---|
| CLI/TUI | Fast local execution in a terminal, including sessions and scripting |
| Desktop | A local personal workbench for workspaces, sessions, and results |
| Portal | Space work, workflows, background runs, shared outputs, and governance |
Try BuildMax Locally
Download a binary from Releases, or:
go install github.com/gougoujiang/buildmax/cmd/buildmax@latest
Configure a model — this writes ~/.buildmax/settings.yaml:
buildmax init --api-key sk-your-key-here
buildmax doctor
That sets up openai/gpt-4o-mini through OpenRouter. Any OpenAI-compatible
endpoint works; buildmax init --model llama3.1 --api-url http://localhost:11434/v1
points it at a local one instead. Omit --api-key to fill the key in later.
buildmax doctor checks the local setup without contacting a model provider.
Then run it against a directory:
buildmax -p "Summarize what this project does" # one prompt, print the answer
buildmax # interactive TUI
The current directory is the agent's workspace — it reads, greps, edits files,
and runs shell commands there, for real. Start in a git tree you can revert, or
in sample-data/ — fifteen throwaway datasets that
exist so you can point the agent at something and watch it work.
Full walkthrough: docs/start/quickstart.md.
Run BuildMax For A Space
A space deployment adds the Server, Portal, and workers around the same Agent Core. The fastest complete path is Docker Compose:
git clone https://github.com/gougoujiang/buildmax.git
cd buildmax
./make compose smoke
The smoke uses a deterministic model, needs no provider key, and proves a full
conversation, background TaskRun, and artifact round trip. Compose is the
single-machine evaluation and contributor path. For an interactive deployment
or a private cluster, start with the
Compose quickstart, the
deployment overview and the readable Kubernetes
reference under deployment/production/.
The support matrix states the current Alpha/Beta
boundaries; do not expose a deployment before reading the
authentication and
sandbox guidance.
Documentation
docs/ is the index.
| Install · Quickstart · Support matrix · Concepts | Getting started |
| Hooks · Sandbox | Controlling what the agent may do |
| Compose quickstart · Local kind · Deployment · Authentication | Running it for a space |
| Configuration · CLI · Webhook | Reference |
| docs/ROADMAP.md · Design records | Where it is going, and why |
| Contributing · Support · Changelog | Project participation and releases |
Help Shape BuildMax
BuildMax is early enough that important runtime and product decisions are still being made in public.
Tests are the sharpest current need. The codebase evolves quickly, so a pull request that adds regression coverage for existing, currently-untested behavior is as valuable as new capability and does not need a design discussion first: see Testing.
Contributions are also welcome in four main areas:
- Agent Runtime — tool calling, context durability, models, MCP, skills, subagents, and traces
- Local Experience — CLI/TUI, Desktop, workspaces, sessions, and results
- Enterprise Platform — Portal, workers, managed models, deployment, and space governance
- Trust And Security — sandboxing, permissions, credentials, hooks, audit, and observable execution boundaries
Start with the contribution areas, then choose a
good first issue,
help wanted,
or
agent-ready
task. The last label means the issue has explicit scope, acceptance criteria,
and verification commands; it does not require using an AI agent.
The complete first-contribution path takes about fifteen minutes and needs no model API key: Your First Pull Request.
Build From Source
./make doctor # check contributor tool versions without changing anything
./make build cli # just the CLI — Go is the only tool this needs
./make test # go test ./... against ./testing-sandbox
./make check go # the Go half of what a pull request runs
./make check ci # everything a pull request runs, except the Windows job
./make build # everything, including the three frontends: also needs Node
./make run server # run the already-built buildmax-server
./make run portal # Portal dev server
The Go in go.mod and git are enough for ./make doctor, ./make build cli,
./make test, and ./make check go — a complete Go contribution loop. Anything
that builds a frontend needs the Node in .node-version as well: ./make build,
./make check ci, and ./make run portal. On Windows use make.bat with the
same commands — both forward to the Go task runner in tools/mk. ./make help
lists every command, grouped by what it is for, with the contributor path under
it, and ./make help <command> — or <command> --help — shows one command's
arguments and examples. None of build, test, check, or lint needs a model API
key.
Two directories in the tree are fixtures rather than product code:
sample-data/ holds the datasets above — upload them
into a space workspace to give a fresh Portal deployment something to work on, or
point the CLI at one — and evaluation/suite/ holds the evaluation tasks, each
with the state a trial starts from and the graders it is judged by. Run the CLI
tasks with ./make eval; select worker tasks explicitly with
./make eval --surface worker, or both with --surface all.
New here? docs/contribute/first-pr.md is the whole path from clone to pull request. Repository tree: docs/contribute/repo-layout.md.
Security
BuildMax invokes model-selected tools and shell commands. Treat every runtime configuration as an execution boundary: dedicated credentials, least-privilege workspace access, an explicit network policy. The bash sandbox and runtime hooks tighten that boundary, but do not replace reviewing what a deployment is allowed to reach. Never commit credentials.
Report vulnerabilities privately: SECURITY.md.
Community
Use GitHub Discussions for setup questions, early product ideas, deployment experience, and show and tell. Confirmed bugs and contributor-ready work belong in Issues.
Read CONTRIBUTING.md for development checks, architectural boundaries, and pull request guidance. Community participation follows the Code of Conduct; support routes and project decision rules are documented in SUPPORT.md and GOVERNANCE.md.
License And Name
Licensed under the Apache License 2.0. The BuildMax name and logo are not granted by that license; see TRADEMARKS.md.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
buildmax
command
Package main is the entry point for the BuildMax CLI.
|
Package main is the entry point for the BuildMax CLI. |
|
buildmax-desktop
command
Package main is the entry point for the BuildMax desktop app (Wails).
|
Package main is the entry point for the BuildMax desktop app (Wails). |
|
buildmax-server
command
Package main is the entry point for the BuildMax HTTP server (backend for portal).
|
Package main is the entry point for the BuildMax HTTP server (backend for portal). |
|
buildmax-worker
command
Package main is the entry point for the BuildMax worker (runs a single task run via API + direct storage).
|
Package main is the entry point for the BuildMax worker (runs a single task run via API + direct storage). |
|
deployment
|
|
|
smoke/mock-llm
command
Command mock-llm serves the deployment smokes a model that never varies.
|
Command mock-llm serves the deployment smokes a model that never varies. |
|
Package desktop holds the desktop app frontend assets.
|
Package desktop holds the desktop app frontend assets. |
|
evaluation
|
|
|
adapter
Package adapter runs a trial against a built BuildMax artifact and returns a canonical bundle.
|
Package adapter runs a trial against a built BuildMax artifact and returns a canonical bundle. |
|
contract
Package contract defines the BuildMax-owned evaluation contract: the task, subject, trial, grader, and experiment shapes every runner, adapter, and viewer agrees on.
|
Package contract defines the BuildMax-owned evaluation contract: the task, subject, trial, grader, and experiment shapes every runner, adapter, and viewer agrees on. |
|
grader
Package grader turns a finished trial into per-dimension verdicts.
|
Package grader turns a finished trial into per-dimension verdicts. |
|
harbor
Package harbor holds what BuildMax needs to be measured by Harbor against Terminal-Bench 2.1: the versions a result depends on, and the Python agent Harbor loads to run the built CLI inside a task container.
|
Package harbor holds what BuildMax needs to be measured by Harbor against Terminal-Bench 2.1: the versions a result depends on, and the Python agent Harbor loads to run the built CLI inside a task container. |
|
runner
Package runner executes an experiment: every task, repeated, against one or more subjects, and turns the resulting bundles into a comparable report.
|
Package runner executes an experiment: every task, repeated, against one or more subjects, and turns the resulting bundles into a comparable report. |
|
trace
Package trace reads the durable JSONL trace a BuildMax run records.
|
Package trace reads the durable JSONL trace a BuildMax run records. |
|
internal
|
|
|
agentapp/job
Package job owns the local background jobs of one AgentApp: identity, state, bounded output, stop, lifecycle events, and shutdown.
|
Package job owns the local background jobs of one AgentApp: identity, state, bounded output, stop, lifecycle events, and shutdown. |
|
agentapp/taskrun
Package taskrun provides task-run execution.
|
Package taskrun provides task-run execution. |
|
bootstrap
Package bootstrap wires process startup dependencies.
|
Package bootstrap wires process startup dependencies. |
|
config
Package config provides configuration loading and defaults.
|
Package config provides configuration loading and defaults. |
|
core/agent
Package agent provides the core AI agent logic: task planning, tool invocation, and conversation.
|
Package agent provides the core AI agent logic: task planning, tool invocation, and conversation. |
|
core/apierr
Package apierr is the vocabulary a service uses to say why it refused.
|
Package apierr is the vocabulary a service uses to say why it refused. |
|
core/hook
Package hook holds the shape of a hooks configuration block and the naming its events and transports use.
|
Package hook holds the shape of a hooks configuration block and the naming its events and transports use. |
|
core/llm
Package llm holds LLM wire types and the Tool contract used across core services and agent execution.
|
Package llm holds LLM wire types and the Tool contract used across core services and agent execution. |
|
core/localproject
Package localproject owns the local Project: the stable identity that groups the sessions of one local unit of work across CLI, TUI, and Desktop, and that will own the first cross-session memory scope.
|
Package localproject owns the local Project: the stable identity that groups the sessions of one local unit of work across CLI, TUI, and Desktop, and that will own the first cross-session memory scope. |
|
core/mcp
Package mcp holds the shape of an mcp.json document and the rules a server definition must satisfy.
|
Package mcp holds the shape of an mcp.json document and the rules a server definition must satisfy. |
|
core/plugin
Package plugin owns the plugin manifest: its format, its rules, and the version arithmetic that decides whether a build may run a release.
|
Package plugin owns the plugin manifest: its format, its rules, and the version arithmetic that decides whether a build may run a release. |
|
core/schema
Package schema is what a database says has been done to it.
|
Package schema is what a database says has been done to it. |
|
core/secret
Package secret owns the Space Secret domain: a Space-owned group of named items, its lifecycle, and the store contract.
|
Package secret owns the Space Secret domain: a Space-owned group of named items, its lifecycle, and the store contract. |
|
core/session
Package session provides the core session model: identity, the linked history journal, the reducer that replays it, recovery analysis, and the persistence seam.
|
Package session provides the core session model: identity, the linked history journal, the reducer that replays it, recovery analysis, and the persistence seam. |
|
core/space
Package space owns what a space's roles may do.
|
Package space owns what a space's roles may do. |
|
core/subagent
Package subagent holds the shape of a subagent definition file and the rules its frontmatter must satisfy.
|
Package subagent holds the shape of a subagent definition file and the rules its frontmatter must satisfy. |
|
e2e/cli
Package clie2e drives the built CLI binary end to end against a scripted model.
|
Package clie2e drives the built CLI binary end to end against a scripted model. |
|
infra/db
Package db provides persistence for BuildMax backend entities (MySQL via GORM).
|
Package db provides persistence for BuildMax backend entities (MySQL via GORM). |
|
infra/flock
Package flock is an advisory file lock that the operating system releases when the holding process exits.
|
Package flock is an advisory file lock that the operating system releases when the holding process exits. |
|
infra/httpclient
Package httpclient decodes the error envelope the BuildMax server writes.
|
Package httpclient decodes the error envelope the BuildMax server writes. |
|
infra/llm
Package llm implements the core/llm.LLMClient contract over the LLM wire protocols BuildMax speaks: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Ollama's native local API.
|
Package llm implements the core/llm.LLMClient contract over the LLM wire protocols BuildMax speaks: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, and Ollama's native local API. |
|
infra/llmremote
Package llmremote implements the core LLM contract against a BuildMax managed gateway instead of a provider.
|
Package llmremote implements the core LLM contract against a BuildMax managed gateway instead of a provider. |
|
infra/llmwire
Package llmwire is the versioned wire contract for BuildMax managed inference.
|
Package llmwire is the versioned wire contract for BuildMax managed inference. |
|
infra/localprojectstore
Package localprojectstore is the file backend for local Projects: the bundle under projects/<project_id>/, the rebuildable catalog projection beside it, and the writer lock that serializes changes to either.
|
Package localprojectstore is the file backend for local Projects: the bundle under projects/<project_id>/, the rebuildable catalog projection beside it, and the writer lock that serializes changes to either. |
|
infra/log
Package log configures the application's default slog logger.
|
Package log configures the application's default slog logger. |
|
infra/objectstore
Package objectstore provides pluggable blob storage for space workspace files and task-run artifacts.
|
Package objectstore provides pluggable blob storage for space workspace files and task-run artifacts. |
|
infra/pluginarchive
Package archive packs and extracts a plugin package.
|
Package archive packs and extracts a plugin package. |
|
infra/pluginwire
Package pluginwire is the wire contract for the private plugin Marketplace.
|
Package pluginwire is the wire contract for the private plugin Marketplace. |
|
infra/proc
Package proc starts and supervises the OS processes behind local background jobs: process-group spawning, bounded output capture, and process-tree termination.
|
Package proc starts and supervises the OS processes behind local background jobs: process-group spawning, bounded output capture, and process-tree termination. |
|
infra/sandbox
Package sandbox provides the OS-level bash subprocess sandbox.
|
Package sandbox provides the OS-level bash subprocess sandbox. |
|
infra/secret
Package secret implements the cryptography behind Space Secrets: envelope encryption of a Secret's item map, and the key-encryption-key providers that wrap the per-write data keys.
|
Package secret implements the cryptography behind Space Secrets: envelope encryption of a Secret's item map, and the key-encryption-key providers that wrap the per-write data keys. |
|
infra/sessionstore
Package sessionstore is the file backend for local sessions: the JSONL journal codec, the single-writer lock, and tail repair.
|
Package sessionstore is the file backend for local sessions: the JSONL journal codec, the single-writer lock, and tail repair. |
|
infra/trace
Package trace persists a durable, bounded, redacted record of a single Agent run by consuming the core/agent event stream.
|
Package trace persists a durable, bounded, redacted record of a single Agent run by consuming the core/agent event stream. |
|
infra/workerclient
Package workerclient defines the worker API client and HTTP contract types.
|
Package workerclient defines the worker API client and HTTP contract types. |
|
infra/wsarchive
Package wsarchive encodes and decodes a Task workspace checkpoint's payload: one Zstandard-compressed tar archive, format tar.zst.v1.
|
Package wsarchive encodes and decodes a Task workspace checkpoint's payload: one Zstandard-compressed tar archive, format tar.zst.v1. |
|
interface/auth
Package auth provides credential persistence and renewal for the BuildMax client.
|
Package auth provides credential persistence and renewal for the BuildMax client. |
|
interface/cli
Package cli: root and subcommands for the BuildMax CLI.
|
Package cli: root and subcommands for the BuildMax CLI. |
|
interface/client
Package client provides an HTTP client for the BuildMax server API.
|
Package client provides an HTTP client for the BuildMax server API. |
|
interface/desktop
Package desktop implements the BuildMax desktop app (Wails) and is used by cmd/buildmax-desktop.
|
Package desktop implements the BuildMax desktop app (Wails) and is used by cmd/buildmax-desktop. |
|
interface/pluginmgr
Package pluginmgr installs plugins from a deployment's Marketplace.
|
Package pluginmgr installs plugins from a deployment's Marketplace. |
|
interface/slashcmd
Package slashcmd is the single source of truth for the runtime chat's slash-command set.
|
Package slashcmd is the single source of truth for the runtime chat's slash-command set. |
|
mock
Package mock provides test-only in-memory implementations for unit tests.
|
Package mock provides test-only in-memory implementations for unit tests. |
|
server
Package server provides the HTTP server for BuildMax.
|
Package server provides the HTTP server for BuildMax. |
|
server/access
Package access owns who a caller is and what they may do.
|
Package access owns who a caller is and what they may do. |
|
server/authtoken
Package authtoken signs and verifies the run token a worker presents to the managed LLM gateway.
|
Package authtoken signs and verifies the run token a worker presents to the managed LLM gateway. |
|
server/handlers/admin
Package admin serves the deployment-scoped routes.
|
Package admin serves the deployment-scoped routes. |
|
server/handlers/artifact
Package artifact serves the durable files a space keeps.
|
Package artifact serves the durable files a space keeps. |
|
server/handlers/auditexport
Package auditexport streams the audit trail as CSV.
|
Package auditexport streams the audit trail as CSV. |
|
server/handlers/auth
Package auth serves the routes that establish a session.
|
Package auth serves the routes that establish a session. |
|
server/handlers/llmhttp
Package llmhttp presents the managed gateway over HTTP.
|
Package llmhttp presents the managed gateway over HTTP. |
|
server/handlers/runterminal
Package runterminal announces a task run that reached a terminal status.
|
Package runterminal announces a task run that reached a terminal status. |
|
server/handlers/space
Package space serves what a space owns: its membership, its agents, its webhook keys, its consumption, and its audit trail.
|
Package space serves what a space owns: its membership, its agents, its webhook keys, its consumption, and its audit trail. |
|
server/handlers/work
Package work serves the surface a space does its work on: issues and their comments, workflows, tasks and the runs that execute them, the conversations that start them, and the files and traces they leave behind.
|
Package work serves the surface a space does its work on: issues and their comments, workflows, tasks and the runs that execute them, the conversations that start them, and the files and traces they leave behind. |
|
server/handlers/worker
Package worker serves the routes a running worker calls back on.
|
Package worker serves the routes a running worker calls back on. |
|
server/scheduler
Package scheduler provides task run scheduling.
|
Package scheduler provides task run scheduling. |
|
server/turnqueue
Package turnqueue serializes the turns of one conversation.
|
Package turnqueue serializes the turns of one conversation. |
|
server/websocket
Package streamhub provides task-scoped stream buffers for worker-push and client subscribe (SSE).
|
Package streamhub provides task-scoped stream buffers for worker-push and client subscribe (SSE). |
|
service/agent
Package agent owns the rules for a space's agent definitions.
|
Package agent owns the rules for a space's agent definitions. |
|
service/artifact
Package artifact keeps durable files on a space's behalf.
|
Package artifact keeps durable files on a space's behalf. |
|
service/audit
Package audit records that a sensitive action happened.
|
Package audit records that a sensitive action happened. |
|
service/identity
Package identity owns what proves who a caller is.
|
Package identity owns what proves who a caller is. |
|
service/llmcatalog
Package llmcatalog owns what a deployment's model catalog will accept and what changing it records.
|
Package llmcatalog owns what a deployment's model catalog will accept and what changing it records. |
|
service/llmgateway
Package llmgateway resolves a model name to an operator-approved upstream target.
|
Package llmgateway resolves a model name to an operator-approved upstream target. |
|
service/plugin
Package plugin owns publication and the catalog lifecycle for the private Marketplace.
|
Package plugin owns publication and the catalog lifecycle for the private Marketplace. |
|
service/plugininspect
Package inspect derives a bounded, sanitized description of what a plugin package contributes.
|
Package inspect derives a bounded, sanitized description of what a plugin package contributes. |
|
service/secret
Package secret is the Space Secret lifecycle service: it validates a Secret's items, seals them through a Sealer, and stores metadata plus sealed bytes.
|
Package secret is the Space Secret lifecycle service: it validates a Secret's items, seals them through a Sealer, and stores metadata plus sealed bytes. |
|
service/space
Package space owns membership rules: who is in a space, who may change that, and what a member may be.
|
Package space owns membership rules: who is in a space, who may change that, and what a member may be. |
|
service/systemadmin
Package systemadmin owns who holds a deployment-scoped role.
|
Package systemadmin owns who holds a deployment-scoped role. |
|
service/workspace
Package workspace owns the cross-storage commit of a Task workspace checkpoint: it validates a captured payload's descriptor, confirms the immutable bytes are already durable in the payload store, and only then records the authoritative metadata pointer through the metadata store.
|
Package workspace owns the cross-storage commit of a Task workspace checkpoint: it validates a captured payload's descriptor, confirms the immutable bytes are already durable in the payload store, and only then records the authoritative metadata pointer through the metadata store. |
|
testsupport
Package testsupport holds helpers that exist only for tests.
|
Package testsupport holds helpers that exist only for tests. |
|
testsupport/mockllm
Package mockllm serves scripted model replies over the three wire protocols BuildMax speaks, so an end-to-end suite can drive a real run without a provider, a key, or a paid call.
|
Package mockllm serves scripted model replies over the three wire protocols BuildMax speaks, so an end-to-end suite can drive a real run without a provider, a key, or a paid call. |
|
tool
Package tool provides concrete agent tools.
|
Package tool provides concrete agent tools. |
|
util
Package util contains small, cross-layer helpers with no business ownership.
|
Package util contains small, cross-layer helpers with no business ownership. |
|
util/secretscan
Package secretscan recognizes common secret shapes in free text.
|
Package secretscan recognizes common secret shapes in free text. |
|
tools
|
|
|
eval
command
Package main is the entry point for the BuildMax evaluation runner.
|
Package main is the entry point for the BuildMax evaluation runner. |
|
mcp
command
Command mcp is a small MCP server for local testing of BuildMax MCP integration.
|
Command mcp is a small MCP server for local testing of BuildMax MCP integration. |
|
mk
command
License chores: the third-party notice file shipped with every release, and the npm production-dependency license policy.
|
License chores: the third-party notice file shipped with every release, and the npm production-dependency license policy. |
Click to show internal directories.
Click to hide internal directories.