Documentation
¶
Overview ¶
Package sandbox provides Docker sandbox lifecycle management including creation, detection, argument building, and environment forwarding.
Index ¶
- func CanonicalFilePath(path string) (string, error)
- func CanonicalPath(path string) (string, error)
- func EnvForAgent(ctx context.Context, agentRef string, env environment.Provider, ...) (flags, envVars []string)
- func EnvForSource(ctx context.Context, source config.Source, env environment.Provider, ...) (flags, envVars []string)
- func ExtraWorkspace(wd, agentRef string) string
- func ExtraWorkspaceForSource(wd string, source config.Source) string
- func GuestAgentRef(ctx context.Context, source config.Source) (ref, extra string, err error)
- func LoginKit(gateway string, v3 bool) (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, tty bool, ...) *exec.Cmd
- func (b *Backend) CheckAvailable(ctx context.Context) error
- func (b *Backend) CreateCloud(ctx context.Context, opts Options, stderr io.Writer) (string, error)
- func (b *Backend) Ensure(ctx context.Context, wd string, extras []string, configDir, loginKit string, ...) (string, error)
- func (b *Backend) ForWorkspace(ctx context.Context, wd string) *Existing
- func (b *Backend) Stop(ctx context.Context, name string, stderr io.Writer) error
- type Existing
- type Options
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CanonicalFilePath ¶ added in v1.144.0
CanonicalFilePath preserves the final symlink: config-relative files resolve beside the named YAML, not beside its link target.
func CanonicalPath ¶ added in v1.144.0
CanonicalPath resolves links and stored casing, including the existing parent of a path that will be created later. Mounts and guest paths must agree.
func EnvForAgent ¶
func EnvForAgent(ctx context.Context, agentRef string, env environment.Provider, flavors []string, defaults ...*config.RuntimeConfig) (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 EnvForSource ¶ added in v1.144.0
func EnvForSource(ctx context.Context, source config.Source, env environment.Provider, flavors []string, defaults ...*config.RuntimeConfig) (flags, envVars []string)
EnvForSource collects credentials from the already resolved agent selection.
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 sources.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 ExtraWorkspaceForSource ¶ added in v1.144.0
ExtraWorkspaceForSource uses the frozen selection rather than reloading aliases.
func GuestAgentRef ¶ added in v1.144.0
GuestAgentRef pins built-ins to a file so the guest cannot resolve their names through a different alias in the mounted user configuration.
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, tty bool, cagentArgs, envFlags, envVars []string) *exec.Cmd
BuildExecCmd assembles the sandbox exec command.
func (*Backend) CheckAvailable ¶ added in v1.44.0
CheckAvailable checks the selected CLI without requiring a local daemon.
func (*Backend) CreateCloud ¶ added in v1.144.0
CreateCloud uses run's build target, which supports v3 source kits and multi-kit assembly. Detached run creates the sandbox without starting a TUI.
func (*Backend) Ensure ¶ added in v1.44.0
func (b *Backend) Ensure(ctx context.Context, wd string, extras []string, configDir, loginKit string, opts Options) (string, error)
Ensure reuses only the sandbox named for this launch configuration. Other sandboxes, including older docker-agent sandboxes, are never removed.
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 ¶
type Existing struct {
ID string `json:"id"`
Name string `json:"name"`
Workspaces []string `json:"workspaces"`
}
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.
type Options ¶ added in v1.144.0
type Options struct {
Cloud bool
Template string
Workload string
Kits []string
KitArgs []string
TTL time.Duration
}
Options selects the sandbox launch source. Kits are resolved and validated by sbx, including v3 composition, permissions, arguments, and build caching.
Source Files
Directories