docker

Documentation

Overview

Package docker is the Phase 1 Runtime implementation backed by a local Docker daemon via github.com/docker/docker/client.

Sandboxes are plain Docker containers. The sandbox ID is used verbatim as the container name, so lookups go directly through the Docker API without an auxiliary bookkeeping layer. A label (edvabe.sandbox.id=<id>) is also stamped on every container so a future reconnect flow can enumerate orphans on edvabe restart.

Index

• Constants
• func DiscoverHost() (string, error)
• type Runtime
  • func New() (*Runtime, error)
  • func (r *Runtime) AgentEndpoint(sandboxID string) (host string, port int, err error)
  • func (r *Runtime) BuildImage(ctx context.Context, req runtime.BuildRequest) error
  • func (r *Runtime) Close() error
  • func (r *Runtime) Commit(ctx context.Context, sandboxID, imageTag string) error
  • func (r *Runtime) Create(ctx context.Context, req runtime.CreateRequest) (*runtime.SandboxHandle, error)
  • func (r *Runtime) Destroy(ctx context.Context, sandboxID string) error
  • func (r *Runtime) Host() string
  • func (r *Runtime) ListManaged(ctx context.Context) ([]runtime.ManagedContainer, error)
  • func (r *Runtime) Name() string
  • func (r *Runtime) Network() string
  • func (r *Runtime) OwnIPv4() string
  • func (r *Runtime) Pause(ctx context.Context, sandboxID string) error
  • func (r *Runtime) Start(ctx context.Context, sandboxID string) error
  • func (r *Runtime) Stats(ctx context.Context, sandboxID string) (*runtime.Stats, error)
  • func (r *Runtime) Stop(ctx context.Context, sandboxID string) error
  • func (r *Runtime) Unpause(ctx context.Context, sandboxID string) error

Constants

const (
	// LabelSandboxID stamps the sandbox ID on every container edvabe
	// creates. Used by doctor / future reconnect to enumerate managed
	// containers.
	LabelSandboxID = "edvabe.sandbox.id"
	// LabelManaged is a truthy marker so operators can filter edvabe's
	// containers apart from hand-launched ones.
	LabelManaged = "edvabe.managed"
)

Functions

func DiscoverHost

func DiscoverHost() (string, error)

DiscoverHost returns the Docker host URI to connect to, honoring DOCKER_HOST and otherwise probing the well-known socket paths in the order below. The first path that stats returns the URI `unix://<path>`.

1. $DOCKER_HOST (unchanged — may be tcp://, ssh://, unix://)
2. /var/run/docker.sock — Docker Desktop / upstream
3. ~/.colima/docker.sock — Colima default profile
4. ~/.orbstack/run/docker.sock — OrbStack
5. ~/.local/share/containers/podman/machine/podman.sock — Podman

Types

type Runtime

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

Runtime implements runtime.Runtime against a local Docker daemon.

The zero value is not usable — construct with New.

func New

func New() (*Runtime, error)

New constructs a Docker-backed Runtime, discovering the daemon socket via DOCKER_HOST or a list of well-known paths (Docker Desktop, Colima, OrbStack, Podman). Negotiates the Docker API version on first call so the client works across daemon versions.

The Docker network sandbox containers are attached to is resolved in this order:

1. EDVABE_DOCKER_NETWORK env var (or --docker-network flag) — explicit
2. Auto-detected from edvabe's own container's networks when edvabe runs inside Docker / Compose — zero-config for the common case
3. Default Docker `bridge` network

(2) makes Docker Compose deployments work without the user having to look up and configure the compose network name.

func (*Runtime) AgentEndpoint

func (r *Runtime) AgentEndpoint(sandboxID string) (host string, port int, err error)

AgentEndpoint returns the host:port the reverse proxy should forward envd traffic to for a given sandbox. First consults the in-memory cache (populated by Create), then falls back to a live ContainerInspect so the call still works if edvabe restarts mid-sandbox.

func (*Runtime) BuildImage

func (r *Runtime) BuildImage(ctx context.Context, req runtime.BuildRequest) error

BuildImage builds an image from a filesystem build context. Used by the upstream AgentProvider and by the template builder. Consumes the full build output stream before returning so the image is ready when BuildImage returns. If req.LogWriter is non-nil, each line of docker daemon output is forwarded to it as the build progresses.

func (*Runtime) Close

func (r *Runtime) Close() error

Close releases the underlying Docker client's HTTP resources.

func (*Runtime) Commit

func (r *Runtime) Commit(ctx context.Context, sandboxID, imageTag string) error

Commit snapshots a sandbox container's filesystem as a new image tagged imageTag. Uses `docker commit` — so the resulting image captures writable-layer mutations (installed packages, created files) but NOT running process memory. Callers should pause the container first if they need a consistent snapshot.

func (*Runtime) Create

func (r *Runtime) Create(ctx context.Context, req runtime.CreateRequest) (*runtime.SandboxHandle, error)

Create creates + starts a container from req.Image, names it after req.SandboxID, and resolves its bridge IP for the reverse proxy. On any error after ContainerCreate, the partial container is force-removed so the caller doesn't have to clean up.

func (*Runtime) Destroy

func (r *Runtime) Destroy(ctx context.Context, sandboxID string) error

Destroy stops and removes the container named after sandboxID. The Force flag terminates the process without waiting for a graceful shutdown; Phase 1 prioritizes teardown speed over clean exits.

func (*Runtime) Host

func (r *Runtime) Host() string

Host reports the Docker host URI the runtime resolved to (useful for logging and doctor output).

func (*Runtime) ListManaged

func (r *Runtime) ListManaged(ctx context.Context) ([]runtime.ManagedContainer, error)

ListManaged enumerates containers labeled edvabe.managed=true (including paused and stopped) and returns a normalized view. Individual inspect failures are swallowed — the caller is rehydrating on startup, one bad container shouldn't abort the whole sweep. Containers in transitional states (dead / removing / created but never started) are filtered out so the manager only sees entries it can act on.

func (*Runtime) Name

func (r *Runtime) Name() string

Name is "docker".

func (*Runtime) Network

func (r *Runtime) Network() string

Network reports the Docker network name sandbox containers are attached to ("" means default bridge).

func (*Runtime) OwnIPv4

func (r *Runtime) OwnIPv4() string

OwnIPv4 returns edvabe's own IPv4 address on the sandbox network, or "" when it can't be determined (not containerized, inspection failed, etc.). Used to default --dns-answer.

func (*Runtime) Pause

func (r *Runtime) Pause(ctx context.Context, sandboxID string) error

Pause freezes the container's processes via `docker pause`. The container stays resident in memory and keeps its network namespace; Unpause thaws it again. This is NOT a memory snapshot — rebooting the host drops the state. Callers surface that caveat to users.

func (*Runtime) Start

func (r *Runtime) Start(ctx context.Context, sandboxID string) error

Start boots a previously stopped container and refreshes the cached agent endpoint. Docker may assign a new bridge IP after restart, so we re-inspect and overwrite the entry the reverse proxy consults.

func (*Runtime) Stats

func (r *Runtime) Stats(ctx context.Context, sandboxID string) (*runtime.Stats, error)

Stats returns resource usage for a running sandbox. Asks the daemon to include a prior sample so CPU percentages can be computed from the delta without the caller having to stream and diff samples themselves.

func (*Runtime) Stop

func (r *Runtime) Stop(ctx context.Context, sandboxID string) error

Stop halts the container via `docker stop`. Processes receive SIGTERM then SIGKILL after Docker's default grace period. Memory is released; the writable filesystem layer is preserved so Start can boot it again.

func (*Runtime) Unpause

func (r *Runtime) Unpause(ctx context.Context, sandboxID string) error

Unpause thaws a previously-paused container, resuming all of its processes from where Pause left them.