launch

Documentation

Overview

Package launch bridges resources.Toolbox manifests to running host.Plugin processes. Tiny on purpose — the heavy lifting lives in host (process management) and resources (manifest validation); this package just composes them.

Why not put Launch on *resources.Toolbox directly: resources is a foundational package and adding a dependency on toolbox/host would create a downward-pointing import (toolbox already imports resources via the manifest). Splitting the wire here keeps resources free of plugin-runtime concerns.

Index

• type AdmissionMode
• type Options
• type Plugin
  • func Launch(ctx context.Context, t *resources.Toolbox, opts ...manager.LoadOption) (*Plugin, error)
  • func LaunchWithOptions(ctx context.Context, t *resources.Toolbox, lopts Options, ...) (*Plugin, error)
  • func (p *Plugin) Close()
  • func (p *Plugin) Conn() *manager.AgentConn

Types

type AdmissionMode

type AdmissionMode string

AdmissionMode separates local development/tests from production startup. It is deliberately a typed value rather than an environment variable so the security decision is visible and reviewable at each host composition root.

const (
	AdmissionLocal      AdmissionMode = "local"
	AdmissionProduction AdmissionMode = "production"
)

type Options

type Options struct {
	// Workspace is the absolute path that fills the ${WORKSPACE}
	// placeholder in the manifest's sandbox policy paths. Empty
	// means "${WORKSPACE} is not available" — manifests referencing
	// it will fail to load, which is the right behavior (don't
	// silently substitute "").
	Workspace string

	// SkipSandbox bypasses the OS-level sandbox even when the
	// manifest declares one. ONLY for tests / diagnostics that need
	// to inspect what the plugin would do unconfined; production
	// callers should never set this. Logged via the agent's stderr
	// when active so an audit can flag the bypass.
	SkipSandbox bool

	// Admission selects the startup trust boundary. The zero value is the
	// explicit local-development mode. Production requires non-empty manifest
	// capacity/authority, an enforcing OS sandbox, and manager-level
	// principal/PDP/scoped-authorization wiring.
	Admission AdmissionMode
}

Options tunes Launch beyond the manager.LoadOption surface. Use it for launch-specific behavior — the workspace path that drives the manifest's ${WORKSPACE} expansion, opt-out toggles for the sandbox.

type Plugin

type Plugin struct {

	// Client is the typed Toolbox gRPC client over the AgentConn's
	// shared connection. Direct field rather than accessor — callers
	// pass it around and we don't gain anything from gating access.
	Client toolboxv0.ToolboxClient
	// contains filtered or unexported fields
}

Plugin pairs a running toolbox plugin's manager.AgentConn with a typed ToolboxClient. The connection's lifetime is owned by Plugin; Close tears the plugin process down via the standard agent loader shutdown sequence.

func Launch

func Launch(ctx context.Context, t *resources.Toolbox, opts ...manager.LoadOption) (*Plugin, error)

Launch is the convenience entrypoint: take a resources.Toolbox manifest, spawn the plugin via manager.Load (under the manifest's declared OS sandbox), return a Plugin pairing the connection with the typed Toolbox client.

What this method does that a bare manager.Load doesn't:

1. Standard env injection: CODEFLY_TOOLBOX_{NAME,VERSION,DIR} so plugin binaries can surface accurate Identity values without re-parsing the manifest.
2. Sandbox policy translation: t.Sandbox → sandbox.Sandbox, applied to the spawned process via manager.WithSandbox. The plugin runs under bwrap (Linux) / sandbox-exec (macOS) with the declared read paths, write paths, network policy, and unix sockets. ${WORKSPACE} / ${HOME} / ${TMPDIR} placeholders are expanded against opts.Workspace and the host's environment.

Toolbox-specific runtime config (CODEFLY_TOOLBOX_WORKSPACE for git, CODEFLY_TOOLBOX_ALLOWED_DOMAINS for web, …) is the caller's responsibility — pass it via manager.WithEnv on the LoadOptions.

func LaunchWithOptions

func LaunchWithOptions(ctx context.Context, t *resources.Toolbox, lopts Options, opts ...manager.LoadOption) (*Plugin, error)

LaunchWithOptions is Launch with explicit Options. The bare Launch uses zero-value Options (no Workspace, sandbox enabled). Most callers use this when they need to seed the workspace for sandbox policy expansion.

func (*Plugin) Close

func (p *Plugin) Close()

Close shuts down the plugin process. Idempotent — safe to call in a deferred cleanup block alongside an explicit Close path.

func (*Plugin) Conn

func (p *Plugin) Conn() *manager.AgentConn

Conn exposes the underlying agent connection for callers that need non-Toolbox surfaces on the same plugin (Identity / health / a future RPC the toolbox layer doesn't model). Most callers should use Client; reach for Conn only when you specifically need it.