Quickstart: build your own mast
The mast binary is one line of Go over the github.com/go-steer/mast/cli
package:
func main() { os.Exit(cli.Main(context.Background(), os.Args[1:])) }Your own binary is the same line with options. What you get is the
whole binary — serve mode, one-shot mode, mast sessions, mast stop,
every flag and exit code in the CLI reference, every
listener — plus the models and tools you add. You don’t rebuild the
daemon out of parts, and nothing you add skips the governance mast’s
own models and tools go through.
go get github.com/go-steer/mast@latestA main.go with a model and a tool
Section titled “A main.go with a model and a tool”package main
import ( "context" "os" "strings"
"google.golang.org/adk/v2/model"
"github.com/go-steer/mast/cli" "example.com/acme/llm" // your model client "example.com/acme/tickets" // your tools)
func main() { os.Exit(cli.Main(context.Background(), os.Args[1:], cli.WithModels(func(name string) (model.LLM, bool) { if strings.HasPrefix(name, "acme-") { return llm.New(name), true } return nil, false // anything else goes to mast's own providers }), cli.WithTools("tickets", tickets.Open, tickets.Close), ))}Build it like any Go program, then run it like mast:
go build -o mast-acme ../mast-acme --model=acme-large --workload=triageEvery option takes ADK’s own types —
model.LLM, tool.Tool, tool.Toolset — so nothing you write against
it is a mast type beyond the option functions.
Models
Section titled “Models”cli.WithModels takes a function from a model name to a model. It is
asked first, for every model name the binary meets: the --model value
and each specialist’s model: in the bundle.
Return false and the name goes to mast’s own providers (gemini-*,
claude-*), which refuse a name they do not know, exactly as before. So
a bundle can run its coordinator on your model and one specialist on
Claude, or the other way round.
Three things to know:
- Your model is used as you built it. mast wraps its own providers in a retry for a rate-limited call. It does not wrap yours, because your client owns its retries.
- Budgets meter what your model reports. The budget meter folds the token usage on each response. A model that reports none can’t be held to a cost ceiling by anything. If mast’s pricing catalog doesn’t know your model, its calls are priced at the fallback rate and counted as unpriced, not treated as free (see budgets).
--model=echostill makes everything a fake. Under an offline test model the whole process is a test double, and every specialist’smodel:collapses to it, yours included. Offline tests of a bundle keep working in your binary.
cli.WithTools(name, tools...) adds your tools as one toolset called
name. cli.WithToolset adds a tool.Toolset you already have. Either
way, a specialist reaches it the way it reaches an
MCP server, by naming it in its allowlist:
---name: ticket-filermode: Taskcapability: change_executortools: mcp: - server: tickets # the name you gave WithTools tools: [open_ticket]---Because it works like an MCP server, everything mast already enforces on an allowlist applies:
- A mistyped toolset name is refused at startup. The name is checked against the workload’s MCP servers plus the toolsets your binary supplies; an allowlist is applied by dropping what does not match, so a typo would otherwise grant nothing in silence.
- A read-only specialist still enumerates. It must list the tools it
takes, and each has to be classified read-only in the workload’s
tool_catalog.tools. A read-only specialist with notools.mcpat all would inherit every toolset, so startup refuses that too. - Your tools are mutating until you say otherwise. mast classifies a
tool it does not know as mutating, so its calls go through the
write gate under the workload’s
on_mutationpolicy. By default that means each call parks for an operator’s approval. Mark a toolmutating: falseintool_catalog.toolsonce you’ve decided it only reads. - Names must be distinct. A toolset with an empty name, two toolsets sharing one, or a toolset named like one of the workload’s MCP servers is refused, because an allowlist naming it couldn’t say which it meant.
Version stamping
Section titled “Version stamping”Without any stamping, --version — and the version the attach
capabilities frame and the agent card report — is the mast module your
binary was built against: mast 1.0.0 for a go.mod requiring
github.com/go-steer/mast v1.0.0. (With mast replaced by a local
directory there is no version to report, and it says dev.) To put
your own release identity there instead, stamp it the way mast’s
release does:
go build -ldflags "\ -X github.com/go-steer/mast/internal/version.Version=v1.2.3-acme \ -X github.com/go-steer/mast/internal/version.Commit=$(git rev-parse --short HEAD) \ -X github.com/go-steer/mast/internal/version.Date=$(date -u +%F)" -o mast-acme .What isn’t an option yet
Section titled “What isn’t an option yet”These aren’t oversights. Each waits on something specific, and each
would be added later without breaking a main.go written today:
- A session store of your own. The daemon’s durable machinery — the
spend ledger, guardrail halts, the scheduling lease, the attach
surface’s live tail — sits on the SQL connection behind
--session-db, not on ADK’s session interface. A custom session service would quietly lose all of that. Use--session-dbwith SQLite or Postgres. - Your own authentication. Caller identity is moving to go-steer/purser, and an option can’t name its types until purser reaches v1.
- Your own runner plugins. A plugin has to be ordered relative to the effect outbox and the write gate, and that needs a design, not a flag.
If one of these is what’s stopping you, open an issue saying what you’re building. A named use case is what turns a deferred option into an option.