Documentation
¶
Overview ¶
Package container implements a Docker-based runtime backend for agent sessions.
Each agent runs in an isolated Docker container with tmux inside for session management. This provides process isolation and resource limits while maintaining the same interactive experience as the native tmux backend.
Communication uses `docker exec ... tmux send-keys` — no persistent connections or FIFOs needed.
Index ¶
- func SeedClaudeSettings(volumeDir string) error
- type Backend
- func (b *Backend) AgentStats(ctx context.Context, name string) (ContainerStats, error)
- func (b *Backend) AllStats(ctx context.Context) ([]ContainerStats, error)
- func (b *Backend) AttachCmd(ctx context.Context, name string) *exec.Cmd
- func (b *Backend) Capture(ctx context.Context, name string, lines int) (string, error)
- func (b *Backend) CreateSession(ctx context.Context, name, dir string) error
- func (b *Backend) CreateSessionWithCommand(ctx context.Context, name, dir, command string) error
- func (b *Backend) CreateSessionWithEnv(ctx context.Context, name, dir, command string, env map[string]string) error
- func (b *Backend) HasSession(ctx context.Context, name string) bool
- func (b *Backend) IsRunning(ctx context.Context) bool
- func (b *Backend) KillServer(ctx context.Context) error
- func (b *Backend) KillSession(ctx context.Context, name string) error
- func (b *Backend) ListSessions(ctx context.Context) ([]runtime.Session, error)
- func (b *Backend) PipePane(ctx context.Context, name, logPath string) error
- func (b *Backend) RemoveSession(ctx context.Context, name string) error
- func (b *Backend) RenameSession(ctx context.Context, oldName, newName string) error
- func (b *Backend) SendKeys(ctx context.Context, name, keys string) error
- func (b *Backend) SendKeysWithSubmit(ctx context.Context, name, keys, submitKey string) error
- func (b *Backend) SessionName(name string) string
- func (b *Backend) SetEnvironment(_ context.Context, name, key, value string) error
- type Config
- type ContainerStats
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SeedClaudeSettings ¶
SeedClaudeSettings ensures required settings exist in settings.json. If the file doesn't exist, creates it. If it exists, merges in any missing required fields without overwriting user customizations.
Types ¶
type Backend ¶
type Backend struct {
// contains filtered or unexported fields
}
Backend manages Docker containers as agent sessions. Each container runs tmux internally for interactive session management.
func NewBackend ¶
func NewBackend(cfg Config, prefix, workspacePath string, registry *provider.Registry) (*Backend, error)
NewBackend creates a Docker runtime backend. Returns an error if the Docker daemon is not reachable.
func (*Backend) AgentStats ¶
AgentStats is a convenience method on Backend that collects stats for a single agent.
func (*Backend) AllStats ¶
func (b *Backend) AllStats(ctx context.Context) ([]ContainerStats, error)
AllStats collects stats for all running agents in this workspace.
func (*Backend) AttachCmd ¶
AttachCmd returns an exec.Cmd to attach to the agent's tmux session inside the container.
func (*Backend) CreateSession ¶
CreateSession creates a new container session.
func (*Backend) CreateSessionWithCommand ¶
CreateSessionWithCommand creates a container with a command.
func (*Backend) CreateSessionWithEnv ¶
func (b *Backend) CreateSessionWithEnv(ctx context.Context, name, dir, command string, env map[string]string) error
CreateSessionWithEnv creates a fully isolated Docker container for an agent.
Mounts:
- workspace dir → /workspace (project code)
- .bc/volumes/<agent>/.claude → /home/agent/.claude (persistent Claude state)
- bc-shared-tmp → /tmp/bc-shared (shared volume for cross-container file exchange)
Env vars:
- From the env map (BC_AGENT_ID, BC_AGENT_ROLE, role secrets via bc env)
Everything else (auth, plugins, MCP, settings) is managed by Claude inside the container and persists in the .claude volume across restarts.
func (*Backend) HasSession ¶
HasSession checks if a container exists, is running, AND has a live tmux session inside. A container with only zombie processes is treated as dead so the caller will respawn it rather than reusing a broken session.
func (*Backend) KillServer ¶
KillServer stops and removes all BC containers for this workspace.
func (*Backend) KillSession ¶
KillSession stops and removes a container.
func (*Backend) ListSessions ¶
ListSessions lists RUNNING BC-managed containers for this workspace.
func (*Backend) RemoveSession ¶
RemoveSession stops and removes a container permanently. Called by agent delete, not agent stop.
func (*Backend) RenameSession ¶
RenameSession renames a container.
func (*Backend) SendKeysWithSubmit ¶
SendKeysWithSubmit sends text to the agent's tmux session inside the container via `docker exec ... tmux send-keys`. Stateless — no persistent connections. Text is sent literally (-l flag), then the submit key is sent separately.
func (*Backend) SessionName ¶
SessionName returns the full session name with prefix.
type Config ¶
Config holds Docker runtime configuration.
func ConfigFromWorkspace ¶
func ConfigFromWorkspace(dcfg workspace.DockerRuntimeConfig) Config
ConfigFromWorkspace converts workspace DockerRuntimeConfig to container Config.
type ContainerStats ¶
type ContainerStats struct {
Name string `json:"name"`
CPUPercent float64 `json:"cpu_percent"`
MemoryUsed int64 `json:"memory_used_bytes"`
MemoryLimit int64 `json:"memory_limit_bytes"`
MemoryPercent float64 `json:"memory_percent"`
DiskRead int64 `json:"disk_read_bytes"`
DiskWrite int64 `json:"disk_write_bytes"`
NetRx int64 `json:"net_rx_bytes"`
NetTx int64 `json:"net_tx_bytes"`
PIDs int `json:"pids"`
}
ContainerStats holds resource usage metrics for a single Docker container.
func AllAgentStats ¶
func AllAgentStats(ctx context.Context, containerPrefix string) ([]ContainerStats, error)
AllAgentStats collects resource metrics for all running containers matching the prefix. The prefix should be the bc container prefix (e.g., "bc-<hash>-") to scope results to a single workspace.
func Stats ¶
func Stats(ctx context.Context, containerName string) (ContainerStats, error)
Stats collects resource usage metrics for a single Docker container. Uses one-shot stats (stream=false) via the Docker API on the unix socket to avoid blocking. Returns zero-value stats if the container is not running.
Source Files