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 LoginKit(gateway string) (string, error)
- 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, ...) (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, flavors []string) (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 LoginKit ¶ added in v1.116.0
LoginKit materialises a tiny sbx mixin kit declaring the reserved sbx-login credential service: the sandbox proxy injects the user's fresh Docker login JWT into HTTPS requests to the gateway host, and exports DOCKER_TOKEN inside the sandbox as a proxy-managed sentinel so docker-agent's sign-in preflight passes. The real token never enters the sandbox — the proxy only ever injects it into HTTPS requests to docker.com / *.docker.com hosts.
The kit lives in a deterministic per-host directory under the cache dir; callers mount it read-only so its presence doubles as a reuse marker (see Backend.Ensure).
Returns "" when gateway is empty or is not an HTTPS docker.com URL — any other gateway authenticates by its own means.
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". Both are built from the same source and expose the same command surface; they differ only in the executable, the sub-command prefix, and the env needed to run outside the Docker CLI plugin harness.
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 hosts are joined 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, loginKit 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`. loginKit, when non-empty, is a directory containing an sbx mixin kit (see LoginKit) passed to `create --kit` and also mounted read-only so that sandboxes created without it (or for a different gateway host) are not reused. 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