upstream

Documentation

Overview

Package upstream is the Phase 1 AgentProvider. It builds `edvabe/base:latest` as a multi-stage Docker image: stage 1 compiles upstream envd from a pinned e2b-dev/infra commit; stage 2 starts from the pinned e2bdev/base runtime image and copies the envd binary in. See docs/07-open-questions.md#Q2 for why we layer envd on top of e2bdev/base instead of consuming either side alone.

Index

• Constants
• func BaseImageRef() string
• func EnsureBaseImage(ctx context.Context, tag string) error
• func EnsureCodeInterpreterImage(ctx context.Context, tag string) error
• func EnsureEnvdSource(ctx context.Context, tag string) error
• func PullBase(ctx context.Context) error
• type UpstreamEnvdProvider
  • func New() *UpstreamEnvdProvider
  • func (p *UpstreamEnvdProvider) EnsureImage(ctx context.Context, _ runtime.Runtime, tag string) error
  • func (p *UpstreamEnvdProvider) InitAgent(ctx context.Context, endpoint string, cfg agent.InitConfig) error
  • func (p *UpstreamEnvdProvider) Name() string
  • func (p *UpstreamEnvdProvider) Ping(ctx context.Context, endpoint string) error
  • func (p *UpstreamEnvdProvider) Port() int
  • func (p *UpstreamEnvdProvider) Version() string
  • func (p *UpstreamEnvdProvider) WaitReady(ctx context.Context, endpoint, cmd, accessToken string) error

Constants

const BaseImageDigest = "sha256:11349f027b11281645fd8b7874e94053681a0d374508067c16bf15b00e1161b2"

BaseImageDigest pins a specific OCI image index digest of e2bdev/base:latest. This is NOT a per-arch manifest — Docker resolves the right arch for the host when pulling.

Verified 2026-04-15 via:

curl -sSI -H "Authorization: Bearer <token>" \
    -H "Accept: application/vnd.oci.image.index.v1+json" \
    https://registry-1.docker.io/v2/e2bdev/base/manifests/latest

To bump: re-run the HEAD request and replace this value. Record the bump date in a comment above. Also update the literal digest in assets/Dockerfile.base — Docker build-args can't be used in FROM reference digests.

const BaseImageRepo = "docker.io/e2bdev/base"

BaseImageRepo is the public Docker Hub repository E2B publishes their sandbox base image to. Multi-arch (amd64 + arm64).

const CodeInterpreterRepoSHA = "a1b5f41b2a5c37939d07c4785ee3027cf1c5fcc4"

CodeInterpreterRepoSHA pins the e2b-dev/code-interpreter commit from which the template files (server, config, startup scripts) are cloned at `docker build` time. Bump by picking a newer commit SHA.

const CodeInterpreterTag = "edvabe/code-interpreter:latest"

CodeInterpreterTag is the default image tag for the code-interpreter image that edvabe builds and seeds as a built-in template.

const DefaultEnvdVersion = "0.5.7"

DefaultEnvdVersion is the value edvabe reports as `envdVersion` in Sandbox responses. Pinned per CLAUDE.md golden rule #3 — unlocking the newest code path in every SDK branch depends on this exact string. Not tied to the BaseImageDigest below.

const EnvdSourceSHA = "d9063bd8cc70b5ce653e9f7cd4ede0f1e3de0fef"

EnvdSourceSHA pins the e2b-dev/infra commit from which envd is built at `docker build` time. We build from source because neither e2bdev/base nor any other public E2B Docker image ships envd — their orchestrator injects it outside what ends up on Docker Hub.

Current pin: HEAD of tag `2026.15` (2026-04-09), resolved 2026-04-15 via `gh api repos/e2b-dev/infra/git/refs/tags/2026.15`. Bump by picking a newer tag's commit SHA and updating this const; no Dockerfile edits required (passed as --build-arg).

const EnvdSourceTag = "edvabe/envd-source:latest"

EnvdSourceTag is the image tag the template builder references in its generated COPY --from lines. Keep in sync with internal/template/builder/translate.go's EnvdSourceImage constant.

Functions

func BaseImageRef

func BaseImageRef() string

BaseImageRef returns the fully-qualified digest-pinned reference used when pulling or tagging the upstream base image.

func EnsureBaseImage

func EnsureBaseImage(ctx context.Context, tag string) error

EnsureBaseImage runs a multi-stage `docker build` that compiles envd from source (pinned via EnvdSourceSHA) and layers it onto the pinned e2bdev/base image, producing `tag` — typically "edvabe/base:latest".

The embedded Dockerfile is piped via stdin with an empty build context (`docker build -`). Stdout/stderr are forwarded so the user sees progress during what can be a multi-minute first build.

Idempotent: Docker's layer cache makes re-runs fast once the pinned commit has been built once.

func EnsureCodeInterpreterImage

func EnsureCodeInterpreterImage(ctx context.Context, tag string) error

EnsureCodeInterpreterImage builds the code-interpreter Docker image. The Dockerfile is a multi-stage build that compiles envd from source (shared layer cache with EnsureBaseImage), clones the upstream code-interpreter repo at CodeInterpreterRepoSHA, and assembles the final image with Jupyter, the FastAPI overlay, envd, and edvabe-init.

The build context is a tar stream containing the Dockerfile and edvabe-init.sh (same wrapper as EnsureEnvdSource).

Idempotent: Docker's layer cache makes re-runs fast.

func EnsureEnvdSource

func EnsureEnvdSource(ctx context.Context, tag string) error

EnsureEnvdSource runs `docker build` for the minimal scratch image that holds the envd binary and the edvabe-init wrapper. Unlike EnsureBaseImage, the build context carries two files — the Dockerfile plus edvabe-init.sh — so we ship them over stdin as a tar stream and select the Dockerfile with `-f`.

Idempotent: Docker's layer cache makes re-runs fast, and the envd-builder stage is shared with EnsureBaseImage when both images are built from the same process.

func PullBase

func PullBase(ctx context.Context) error

PullBase ensures the pinned e2bdev/base image is present on the local Docker daemon. Shells out to `docker pull`; the Docker SDK will replace this in task 7 when the runtime package needs it for more than one operation.

Idempotent: `docker pull` by digest is a no-op once the image is already present in the local store.

Types

type UpstreamEnvdProvider

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

UpstreamEnvdProvider is the Phase 1 AgentProvider implementation backed by upstream envd running inside the sandbox container.

func New

func New() *UpstreamEnvdProvider

New returns the default upstream envd provider.

func (*UpstreamEnvdProvider) EnsureImage

func (p *UpstreamEnvdProvider) EnsureImage(ctx context.Context, _ runtime.Runtime, tag string) error

func (*UpstreamEnvdProvider) InitAgent

func (p *UpstreamEnvdProvider) InitAgent(ctx context.Context, endpoint string, cfg agent.InitConfig) error

func (*UpstreamEnvdProvider) Name

func (p *UpstreamEnvdProvider) Name() string

func (*UpstreamEnvdProvider) Ping

func (p *UpstreamEnvdProvider) Ping(ctx context.Context, endpoint string) error

func (*UpstreamEnvdProvider) Port

func (p *UpstreamEnvdProvider) Port() int

func (*UpstreamEnvdProvider) Version

func (p *UpstreamEnvdProvider) Version() string

func (*UpstreamEnvdProvider) WaitReady

func (p *UpstreamEnvdProvider) WaitReady(ctx context.Context, endpoint, cmd, accessToken string) error

WaitReady runs cmd through envd's process.Process/Start RPC in a poll loop until the command exits with status 0 or ctx expires. Empty cmd is the Phase 1 fast path — returns nil without ever touching envd.

Errors are retried silently; only the final failure (after ctx expires) is surfaced to the caller, and it carries the most recent cause so the sandbox manager can log something actionable.