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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
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
}
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 ¶
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:
- Standard env injection: CODEFLY_TOOLBOX_{NAME,VERSION,DIR} so plugin binaries can surface accurate Identity values without re-parsing the manifest.
- 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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
network-victim-toolbox
command
Command network-victim-toolbox is a TEST-ONLY plugin used by the end-to-end sandbox-enforcement tests in core/toolbox/launch.
|
Command network-victim-toolbox is a TEST-ONLY plugin used by the end-to-end sandbox-enforcement tests in core/toolbox/launch. |