Execution core (Go)

Core is a complete hand without hand-written tool handlers: bash with process-group cancellation, file tools confined to a session workspace, a stdio MCP supervisor, per-session cleanup and registered capabilities. One core can serve the BMA cloud and a local brain at the same time. It is Go only, and bash is not a sandbox: every brain runs as the executor’s OS user.

Generated from bma-executor-sdk 1.3.0 and its contract (contracts/bma/executor, protocol bma.executor.v1.1). Install, credentials and quick starts are on the bma-executor-sdk overview; the protocol itself is described in Executor Protocol.

NewCore

Validates the options and creates the work root.

// Not in the TypeScript SDK 1.3.0.

# Not in the Python SDK 1.3.0.

func NewCore(opts CoreOptions) (*Core, error)

type CoreOptions struct {
	// WorkRoot holds every session workspace: WorkRoot/<brain>/<session>.
	WorkRoot string
	// Workspace overrides the per-session directory (for example a machine
	// executor whose sessions all share one directory, or a desktop app
	// mapping a brain to a project folder). Tools are confined to it.
	Workspace func(brain, sessionID string) string
	// MaxSessions bounds active sessions across all attached brains;
	// MaxSessionsPerBrain bounds one brain (defaults to MaxSessions). A full
	// core answers session.assign with executor_busy (-32009, retryable).
	MaxSessions         int
	MaxSessionsPerBrain int
	// MaxMCPServersPerSession bounds session.assign.mcp_servers (default 4).
	MaxMCPServersPerSession int
	// BashTimeout applies when neither tool.call deadline_ms nor the bash
	// timeout_ms is set (default 10 minutes).
	BashTimeout time.Duration
	// MaxOutputBytes caps each captured bash stream (default 1 MiB).
	MaxOutputBytes int
	// InlineResultBytes is the largest bash output returned inline (default
	// 48 KiB, under the 64 KiB control frame). Larger output is uploaded as
	// an artifact when UploadArtifacts is set, otherwise truncated.
	InlineResultBytes int
	// ComputerUse serves computer_observe and computer_action and advertises
	// capabilities.computer_use (for example NewCuaDriver). Nil leaves
	// computer use off: the harness then sends no computer_* tool.
	ComputerUse ComputerUseBackend
	// UploadArtifacts advertises the artifacts capability and offloads large
	// bash results with Client.UploadArtifact. Only environment-scoped
	// executors have an artifact store.
	UploadArtifacts bool
	// Env is set on every bash tool and process and cannot be overridden by
	// a request (for example BMA_HOME).
	Env map[string]string
	// DenyEnv reports executor-private variables (credentials, state paths)
	// that no bash tool, process or stdio MCP server may see: they are
	// dropped from the inherited environment and a request setting one is
	// rejected. NewCore rejects an Env entry it denies.
	DenyEnv func(name string) bool
	// RunAs, when set, is the OS identity every bash tool, process and stdio
	// MCP server runs as, so a privileged executor (for example root) keeps
	// its own credentials and state out of the workload's reach. HOME and
	// USER in bash and process environments are the workload's. File tools
	// (read/write/edit/glob/grep) run inside the executor and would bypass
	// that boundary, so they are refused. Unix only.
	RunAs *RunAs
	// EndAfterToolCall marks sessions that carry exactly one tool call: the
	// core ends them (session.ended "completed") after the result is
	// delivered. BMA's durable selfhost queue assigns such sessions.
	EndAfterToolCall func(SessionAssignParams) bool
	OnLog            func(LogEvent)
}

Register

Adds a capability (a set of methods behind capability bits); call it before Attach.

// Not in the TypeScript SDK 1.3.0.

# Not in the Python SDK 1.3.0.

func (c *Core) Register(capability Capability) error

type Capability struct {
	// Advertise sets the capability bits on the register capabilities.
	Advertise     func(*Capabilities)
	Methods       map[string]Handler
	SessionScoped bool
	OnSessionEnd  func(*CoreSession)
}

Capabilities

What an attached client should advertise.

// Not in the TypeScript SDK 1.3.0.

# Not in the Python SDK 1.3.0.

func (c *Core) Capabilities() Capabilities

Attach

Serves session.assign, session.stop, tool.call and every registered capability for one brain on a client; call it before the client starts. Brain names must be unique per core.

// Not in the TypeScript SDK 1.3.0.

# Not in the Python SDK 1.3.0.

func (c *Core) Attach(brain string, client *Client) error

Close

Stops every session of every brain without reporting session.ended.

// Not in the TypeScript SDK 1.3.0.

# Not in the Python SDK 1.3.0.

func (c *Core) Close()

Env

Builds a bash or process environment from the executor’s base environment, the request env (bounded; loader and denied variables rejected) and CoreOptions.Env.

// Not in the TypeScript SDK 1.3.0.

# Not in the Python SDK 1.3.0.

func (c *Core) Env(explicit map[string]string) ([]string, error)

NewProcessCapability

Serves process.start/read/write/interrupt/terminate/list and process.status on core sessions: pipes or a PTY, cursor-addressed output, idempotent starts and writes, timeouts and process-group signals; nil hooks leave their capability bits unset.

// Not in the TypeScript SDK 1.3.0.

# Not in the Python SDK 1.3.0.

func NewProcessCapability(core *Core, opts ProcessOptions) Capability

type ProcessOptions struct {
	// Env is set on every process (not on bash tools) over the request env,
	// for example a canonical skill root such as BMA_HOME.
	Env            map[string]string
	FileTransfer   FileTransferer
	GitCredentials GitCredentialGranter
	// PackageInstaller serves process.start package_install.
	PackageInstaller PackageInstaller
	// Launch runs before each new command process starts; see LaunchFunc.
	Launch LaunchFunc
	// SessionFiles syncs each agent session's files below its root, which
	// is advertised as capabilities.session_files.root; see SessionFiles.
	SessionFiles *SessionFiles
}

NewSkillInstallCapability

Serves skill.install with your installer; installs run one at a time.

// Not in the TypeScript SDK 1.3.0.

# Not in the Python SDK 1.3.0.

func NewSkillInstallCapability(install SkillInstaller) (Capability, error)

CoreSession

One assigned session of one brain, as seen by a capability.

// Not in the TypeScript SDK 1.3.0.

# Not in the Python SDK 1.3.0.

func (s *CoreSession) ID() string

func (s *CoreSession) Brain() string

func (s *CoreSession) Workspace() string

func (s *CoreSession) Client() *Client

func (s *CoreSession) Context() context.Context

func (s *CoreSession) Assignment() SessionAssignParams

func (s *CoreSession) Value(key any, create func() any) any

func (s *CoreSession) ResolveCwd(cwd string) (string, error)

SDKs

Anthropic SDKs

bma-executor-sdk

NewCore

Register

Capabilities

Attach

Close

Env

NewProcessCapability

NewSkillInstallCapability

CoreSession

​NewCore

​Register

​Capabilities

​Attach

​Close

​Env

​NewProcessCapability

​NewSkillInstallCapability

​CoreSession

NewCore

Register

Capabilities

Attach

Close

Env

NewProcessCapability

NewSkillInstallCapability

CoreSession