sandbox

Documentation

Overview

Package sandbox provides optional Docker isolation for agent shell and code tools.

Index

• type Config
  • func ConfigFromChatAgent(cfg config.ChatAgentSandboxConfig, workspace string) Config
• type DockerRunner
  • func (DockerRunner) Run(ctx context.Context, opts RunOptions) (env.Capture, error)
• type Env
  • func New(cfg Config, host env.ExecutionEnv, runner Runner) *Env
  • func (e *Env) Exec(ctx context.Context, opts env.ExecOptions) result.Result[env.Capture, result.ExecutionError]
  • func (e *Env) MkdirAll(ctx context.Context, path string, perm os.FileMode) result.Result[struct{}, result.FileError]
  • func (e *Env) ReadDir(ctx context.Context, path string) result.Result[[]env.DirEntry, result.FileError]
  • func (e *Env) ReadFile(ctx context.Context, path string) result.Result[[]byte, result.FileError]
  • func (e *Env) Remove(ctx context.Context, path string) result.Result[struct{}, result.FileError]
  • func (e *Env) WriteFile(ctx context.Context, path string, data []byte, perm os.FileMode) result.Result[struct{}, result.FileError]
• type RunOptions
• type Runner

Types

type Config

type Config struct {
	// Image is the container image used for Exec.
	Image string
	// Network is the Docker network mode.
	Network string
	// Memory limits container memory (e.g. "512m").
	Memory string
	// Workspace is the host workspace path bind-mounted at the same path inside the container.
	Workspace string
	// ServerURL is the Flowbot API URL injected for the flowbot CLI inside the container.
	ServerURL string
	// AccessToken is the Hub access token injected for the flowbot CLI inside the container.
	AccessToken string
}

Config configures Docker sandbox execution.

func ConfigFromChatAgent

func ConfigFromChatAgent(cfg config.ChatAgentSandboxConfig, workspace string) Config

ConfigFromChatAgent builds sandbox Config from chat agent settings.

type DockerRunner

type DockerRunner struct{}

DockerRunner runs commands via the Docker Engine API.

func (DockerRunner) Run

func (DockerRunner) Run(ctx context.Context, opts RunOptions) (env.Capture, error)

Run starts an ephemeral container, waits for exit, and returns captured output.

type Env

type Env struct {
	// contains filtered or unexported fields
}

Env implements env.ExecutionEnv with host filesystem ops and sandboxed Exec.

func New

func New(cfg Config, host env.ExecutionEnv, runner Runner) *Env

New creates a sandbox ExecutionEnv. Host FS ops use env.Default when host is nil.

func (*Env) Exec

func (e *Env) Exec(ctx context.Context, opts env.ExecOptions) result.Result[env.Capture, result.ExecutionError]

Exec runs the command inside a sandbox container with the workspace mounted.

func (*Env) MkdirAll

func (e *Env) MkdirAll(ctx context.Context, path string, perm os.FileMode) result.Result[struct{}, result.FileError]

MkdirAll creates directories on the host filesystem.

func (*Env) ReadDir

func (e *Env) ReadDir(ctx context.Context, path string) result.Result[[]env.DirEntry, result.FileError]

ReadDir lists directory entries on the host filesystem.

func (*Env) ReadFile

func (e *Env) ReadFile(ctx context.Context, path string) result.Result[[]byte, result.FileError]

ReadFile reads from the host filesystem.

func (*Env) Remove

func (e *Env) Remove(ctx context.Context, path string) result.Result[struct{}, result.FileError]

Remove deletes a path on the host filesystem.

func (*Env) WriteFile

func (e *Env) WriteFile(ctx context.Context, path string, data []byte, perm os.FileMode) result.Result[struct{}, result.FileError]

WriteFile writes to the host filesystem.

type RunOptions

type RunOptions struct {
	Image       string
	Network     string
	Memory      string
	Workspace   string
	WorkDir     string
	Command     string
	Argv        []string
	ServerURL   string
	AccessToken string
	// CLIConfigDir is a host directory bind-mounted read-only at containerCLIConfigPath.
	// When empty and AccessToken is set, DockerRunner materializes a temporary directory.
	CLIConfigDir string
}

RunOptions configures one sandbox command invocation.

type Runner

type Runner interface {
	Run(ctx context.Context, opts RunOptions) (env.Capture, error)
}

Runner executes a one-shot command inside a sandbox container.