Documentation
¶
Overview ¶
Package sandbox provides Docker sandbox lifecycle management including creation, detection, argument building, and environment forwarding.
Index ¶
- func EnvForAgent(ctx context.Context, agentRef string, env environment.Provider) (flags, envVars []string)
- func ExtraWorkspace(wd, agentRef string) string
- func StartTokenWriterIfNeeded(ctx context.Context, dir, modelsGateway string) func()
- type Backend
- func (b *Backend) AllowHosts(ctx context.Context, name string, hosts []string) error
- func (b *Backend) BuildExecCmd(ctx context.Context, name, wd string, cagentArgs, envFlags, envVars []string) *exec.Cmd
- func (b *Backend) CheckAvailable(ctx context.Context) error
- func (b *Backend) Ensure(ctx context.Context, wd string, extras []string, template, configDir string) (string, error)
- func (b *Backend) ForWorkspace(ctx context.Context, wd string) *Existing
- type Existing
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnvForAgent ¶
func EnvForAgent(ctx context.Context, agentRef string, env environment.Provider) (flags, envVars []string)
EnvForAgent loads the agent config and gathers the environment variables it requires. It returns:
- flags: `-e KEY` args for docker sandbox exec (name only, no value)
- envVars: `KEY=VALUE` entries to set on the exec process environment
Variables that Docker Desktop already proxies are skipped.
func ExtraWorkspace ¶
ExtraWorkspace returns the directory to mount as a read-only extra workspace when the agent file lives outside the main workspace.
The agent reference may be a path, an OCI/URL reference, a built-in name, or an alias defined in the user's config — ExtraWorkspace delegates resolution to config.Resolve so all of those forms are handled the same way runtime code handles them. Only [Source]s that expose a containing directory (i.e. local file sources) produce a mount; OCI / URL / built-in / bytes sources return "" because there is no host file to bind-mount.
Returns "" when no extra mount is needed (the agent file is already under wd), the reference cannot be resolved, or the resolved source has no on-disk parent directory.
func StartTokenWriterIfNeeded ¶
StartTokenWriterIfNeeded starts a background goroutine that refreshes DOCKER_TOKEN into a shared file when a models gateway is configured. Returns a stop function that is safe to call multiple times (and is a no-op when no writer was started).
Types ¶
type Backend ¶ added in v1.44.0
type Backend struct {
// contains filtered or unexported fields
}
Backend describes how to invoke sandbox CLI commands. The two supported backends are "docker sandbox" and "sbx".
func NewBackend ¶ added in v1.44.0
NewBackend returns the appropriate backend. When preferSbx is true and the "sbx" binary is on PATH, the sbx backend is used; otherwise it falls back to "docker sandbox".
func (*Backend) AllowHosts ¶ added in v1.62.0
AllowHosts adds a sandbox-scoped network allow rule for each entry in hosts. Hosts may carry an optional ":port" suffix (e.g. "api.example.com:443"). Returns a non-fatal error: callers usually log and continue, since a partial failure (e.g. a host already allowed by an earlier rule) shouldn't keep the sandbox from running.
Empty entries are silently skipped. Entries that contain a comma are rejected because the sbx backend joins the list with commas when forwarding the rule to the policy engine; allowing them through unescaped would let a single value smuggle several distinct rules into the engine. Entries that contain a literal space are rejected for the same defence-in-depth reason — callers should pass already-split hostnames.
func (*Backend) BuildExecCmd ¶ added in v1.44.0
func (b *Backend) BuildExecCmd(ctx context.Context, name, wd string, cagentArgs, envFlags, envVars []string) *exec.Cmd
BuildExecCmd assembles the sandbox exec command.
func (*Backend) CheckAvailable ¶ added in v1.44.0
CheckAvailable returns a user-friendly error when Docker is not installed or the sandbox feature is not supported.
func (*Backend) Ensure ¶ added in v1.44.0
func (b *Backend) Ensure(ctx context.Context, wd string, extras []string, template, configDir string) (string, error)
Ensure makes sure a sandbox exists for the given workspace, creating or recreating it as needed. extras is a list of additional host directories to mount read-only (kit dir, agent yaml dir, ...). Each entry is made absolute and cleaned; duplicates and entries that resolve to wd are filtered out. When template is non-empty it is passed to `docker sandbox create -t`. Returns the sandbox name.
func (*Backend) ForWorkspace ¶ added in v1.44.0
ForWorkspace returns the existing sandbox whose primary workspace matches wd, or nil if none exists. When several sandboxes share the same primary workspace (e.g. "foo" and "foo-1" left behind by a previous run that couldn't rm cleanly), the first one returned by the backend is picked.
type Existing ¶
Existing holds the name and workspaces of an existing Docker sandbox.
func (*Existing) HasWorkspace ¶
HasWorkspace reports whether the sandbox has dir mounted as a workspace.
Source Files
Directories