README
¶
buildmax
Build Everything with AI.
BuildMax is an out-of-the-box, privately deployable Agent platform. One Go agent runtime, three ways to reach it:
- CLI/TUI — one user, one directory, one terminal
- Desktop — the same local capability in a native Wails app
- Portal — a team: shared work, background execution, results, governance
All three run the same agent loop, the same tools, and the same MCP, skill, and subagent behavior. Use only the local surfaces, deploy only the Portal for your company, or both.
Status: Alpha. Interfaces, deployment guidance, and runtime behavior may change before a stable release. Server authentication is bootstrap-level — an operator creates accounts and issues single-use login codes, and there is no password, SSO, or recovery flow. Read docs/deploy/authentication.md before exposing a server.
Quickstart
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.
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 team |
| Configuration · CLI · Webhook | Reference |
| docs/ROADMAP.md · Design records | Where it is going, and why |
| Contributing · Support · Changelog | Project participation and releases |
How It Works
The Portal separates talking from doing:
Tier 1 conversation ──creates──▶ Tier 2 task / task_run
▲ │
└──────────── reports back ──────────────────┘
Tier 1 is the conversation orchestrator and the only voice to the user. Tier 2 is background execution: a worker materializes the team's files into a run directory, runs the shared agent runtime, writes artifacts, and reports back. A long job never blocks the conversation, and its result always returns through the conversation that started it.
More: docs/start/concepts.md · docs/contribute/architecture/
Build From Source
./make doctor # check contributor tool versions without changing anything
./make build # strict CLI, server, worker, GUI, Portal, Desktop build
./make test # go test ./... against ./testing-sandbox
./make run server # run the already-built buildmax-server
./make run portal # Portal dev server
On Windows use make.bat with the same commands — both forward to the Go task
runner in cmd/mk. ./make help shows the common contributor path;
./make help all shows advanced, deployment, and release commands. None
of build, test, 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 team workspace to give a fresh Portal deployment something to work on, or
point the CLI at one — and eval/ holds the agent benchmark's
deliberately-broken Go modules, run by ./make eval.
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.
For setup questions and early ideas, use GitHub Discussions.
Contributing
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-eval
command
Package main is the entry point for the BuildMax agent benchmark runner.
|
Package main is the entry point for the BuildMax agent benchmark runner. |
|
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). |
|
local-test-mcp-server
command
Command local-test-mcp-server is a small MCP server for local testing of BuildMax MCP integration.
|
Command local-test-mcp-server 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. |
|
deployment
|
|
|
smoke/mock-llm
command
|
|
|
Package desktop holds the desktop app frontend assets.
|
Package desktop holds the desktop app frontend assets. |
|
internal
|
|
|
agentapp/taskrun
Package taskrun provides task-run execution.
|
Package taskrun provides task-run execution. |
|
agenteval
Package agenteval provides a benchmark harness for evaluating agent capability.
|
Package agenteval provides a benchmark harness for evaluating agent capability. |
|
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/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/session
Package session provides the core session model: id, title, created_at, and conversation history.
|
Package session provides the core session model: id, title, created_at, and conversation history. |
|
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/llm
Package llm provides LLM client implementations (OpenRouter/OpenAI-compatible).
|
Package llm provides LLM client implementations (OpenRouter/OpenAI-compatible). |
|
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/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 team workspace files and task-run artifacts.
|
Package objectstore provides pluggable blob storage for team workspace files and task-run artifacts. |
|
infra/sandbox
Package sandbox provides the OS-level bash subprocess sandbox.
|
Package sandbox provides the OS-level bash subprocess sandbox. |
|
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. |
|
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. |
|
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/scheduler
Package scheduler provides task run scheduling.
|
Package scheduler provides task run scheduling. |
|
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/audit
Package audit records that a sensitive action happened.
|
Package audit records that a sensitive action happened. |
|
service/conversation/tool
Package tool contains the Tier 1 conversation tools exposed to the model.
|
Package tool contains the Tier 1 conversation tools exposed to the model. |
|
service/llmgateway
Package llmgateway resolves a team's model alias to an operator-approved upstream target.
|
Package llmgateway resolves a team's model alias to an operator-approved upstream target. |
|
tool
Package tool provides concrete agent tools (Read, Write, Edit, Glob, Grep, Bash, WebFetch, TodoWrite, Skill, Task, and MCP gateway tools).
|
Package tool provides concrete agent tools (Read, Write, Edit, Glob, Grep, Bash, WebFetch, TodoWrite, Skill, Task, and MCP gateway tools). |
|
util
Package util contains small, cross-layer helpers with no business ownership.
|
Package util contains small, cross-layer helpers with no business ownership. |