AI Agent 学习笔记 – 移植

Infra: 镜像构建

Tue, 27 May 2025 00:00:00 +0000

准备工作

编译 envd 二进制

在本地宿主机（linux）上克隆并编译 envd:

# 回到 base 的上级目录
cd /home/sky/work/code/e2b/envd-image-builder

# 克隆官方 infra 仓库（如果慢可以换 github 镜像源）
git clone https://github.com/e2b-dev/infra.git

# 进入 envd 目录
cd infra/packages/envd

# 静态编译出 Linux x64 的二进制文件
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o ../../../base/envd main.go

代码定制

修改默认 host IP

https://deepwiki.com/search/envd-host-ip-169254021_afda741e-0447-47c8-b19d-a63e1c3fa86a?mode=fast

envd 默认使用的 host IP 是 169.254.0.21 ，通过硬编码的方式配置，代码在 packages/envd/internal/port/forward.go

var defaultGatewayIP = net.IPv4(169, 254, 0, 21)

移植到其他环境之后，如果需要修改这个 host IP，比如修改为其他固定值，可以简单修改这行代码。

如果是移植到 k8s 下，sandbox 运行在 pod 中，这里的 host IP 就不是固定值，而是所在 pod 的被分配的 IP 地址。则需要修改 envd 代码，通过某种方式传入 pod IP。

TODO：看怎么修改代码合适。

base 镜像

构建 base 镜像

base 镜像的 Dockerfile:

FROM debian:bookworm-slim

ENV DEBIAN_FRONTEND=noninteractive

# 安装基础系统工具
RUN apt-get update && apt-get install -y --no-install-recommends \
    bash ca-certificates curl git openssh-client procps sudo unzip wget \
    && rm -rf /var/lib/apt/lists/*

# 创建用于 AI 执行代码的普通隔离用户（让 envd 拥有 root 权限，但 AI 执行代码时可以用这个低权限用户）
RUN useradd -m -s /bin/bash sandboxuser && \
    echo "sandboxuser ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers

# 直接把我们在本地编译好的 envd 复制进去
COPY envd /usr/local/bin/envd

# 显式指定工作目录并保持以 ROOT 用户身份运行
WORKDIR /root
USER root

# 暴露官方标准的 49983 端口
EXPOSE 49983

ENTRYPOINT ["/usr/local/bin/envd"]

# 生产默认配置：开启 49983 端口，非纯 Firecracker 兼容模式，开启详细日志
CMD ["-port", "49983", "-isnotfc", "-verbose"]

构建镜像：

docker build -t e2b-base:latest .

查看本地构建好的 e2b-base 镜像：

$ docker images                    

IMAGE                                          ID             DISK USAGE   CONTENT SIZE   EXTRA 
e2b-base:latest                                28d8689e05f8        289MB         72.9MB    U

启动 base 镜像

直接在本机用 docker 启动上面构建好的 e2b base 镜像：

docker run -d \
  --name e2b-base-test \
  --privileged \
  -p 49983:49983 \
  e2b-base:latest

使用完成之后，或者更新代码后重新构建重新运行，关闭已经运行的容器：

docker rm -f e2b-base-test

code interpreter 镜像

TODO

Infra: API验证

Tue, 27 May 2025 00:00:00 +0000

base 镜像

使用上一节构建好的 base 镜像启动 docker，然后验证相关的数据面 API。

envd API

https://e2b.dev/docs/api-reference/envd/check-the-health-of-the-service

Check the health of the service：

curl -i http://localhost:49983/health

HTTP/1.1 204 No Content
Cache-Control: no-store
Content-Type: 
Vary: Origin
Date: Mon, 01 Jun 2026 08:05:52 GMT

Get the stats of the service

curl --request GET --url 'http://localhost:49983/metrics' 

{"ts":1780301268,"cpu_count":32,"cpu_used_pct":0.77,"mem_total_mib":64085,"mem_used_mib":3932,"mem_total":67198607360,"mem_used":4123037696,"mem_cache":4104839168,"disk_used":111465947136,"disk_total":966455894016}

Get the environment variables

curl --request GET --url 'http://localhost:49983/envs'

小结：功能都可用。

file system API

ListDir

curl --request POST --url 'http://localhost:49983/filesystem.Filesystem/ListDir'  \
	--header 'Content-Type: application/json' \
  --data '
{
  "path": "/",
  "depth": 1
}
'

{"entries":[{"name":".dockerenv", "type":"FILE_TYPE_FILE", "path":"/.dockerenv", "mode":493, "permissions":"-rwxr-xr-x", "owner":"root", "group":"root", "modifiedTime":"2026-06-01T07:59:46.609468959Z"}, {"name":"bin", "type":"FILE_TYPE_DIRECTORY", "path":"/bin", "size":"7", "mode":493, "permissions":"Lrwxrwxrwx", "owner":"root", "group":"root", "modifiedTime":"2026-05-18T00:00:00Z", "symlinkTarget":"/usr/bin"}, {"name":"boot", "type":"FILE_TYPE_DIRECTORY", "path":"/boot", "size":"4096", "mode":493, "permissions":"drwxr-xr-x", "owner":"root", "group":"root", "modifiedTime":"2026-05-08T16:15:00Z"}, {"name":"dev", "type":"FILE_TYPE_DIRECTORY", "path":"/dev", "size":"4580", "mode":493, "permissions":"drwxr-xr-x", "owner":"root", "group":"root", "modifiedTime":"2026-06-01T07:59:46.698102456Z"}, {"name":"etc", "type":"FILE_TYPE_DIRECTORY", "path":"/etc", "size":"4096", "mode":493, "permissions":"drwxr-xr-x", "owner":"root", "group":"root", "modifiedTime":"2026-06-01T07:59:46.609639982Z"}, {"name":"home", "type":"FILE_TYPE_DIRECTORY", "path":"/home", "size":"4096", "mode":493, "permissions":"drwxr-xr-x", "owner":"root", "group":"root", "modifiedTime":"2026-06-01T07:27:57Z"}, {"name":"lib", "type":"FILE_TYPE_DIRECTORY", "path":"/lib", "size":"7", "mode":493, "permissions":"Lrwxrwxrwx", "owner":"root", "group":"root", "modifiedTime":"2026-05-18T00:00:00Z", "symlinkTarget":"/usr/lib"}, {"name":"lib64", "type":"FILE_TYPE_DIRECTORY", "path":"/lib64", "size":"9", "mode":493, "permissions":"Lrwxrwxrwx", "owner":"root", "group":"root", "modifiedTime":"2026-05-18T00:00:00Z", "symlinkTarget":"/usr/lib64"}, {"name":"media", "type":"FILE_TYPE_DIRECTORY", "path":"/media", "size":"4096", "mode":493, "permissions":"drwxr-xr-x", "owner":"root", "group":"root", "modifiedTime":"2026-05-18T00:00:00Z"}, {"name":"mnt", "type":"FILE_TYPE_DIRECTORY", "path":"/mnt", "size":"4096", "mode":493, "permissions":"drwxr-xr-x", "owner":"root", "group":"root", "modifiedTime":"2026-05-18T00:00:00Z"}, {"name":"opt", "type":"FILE_TYPE_DIRECTORY", "path":"/opt", "size":"4096", "mode":493, "permissions":"drwxr-xr-x", "owner":"root", "group":"root", "modifiedTime":"2026-05-18T00:00:00Z"}, {"name":"proc", "type":"FILE_TYPE_DIRECTORY", "path":"/proc", "mode":365, "permissions":"dr-xr-xr-x", "owner":"root", "group":"root", "modifiedTime":"2026-06-01T07:59:46.670390345Z"}, {"name":"root", "type":"FILE_TYPE_DIRECTORY", "path":"/root", "size":"4096", "mode":448, "permissions":"drwx------", "owner":"root", "group":"root", "modifiedTime":"2026-05-18T00:00:00Z"}, {"name":"run", "type":"FILE_TYPE_DIRECTORY", "path":"/run", "size":"4096", "mode":493, "permissions":"drwxr-xr-x", "owner":"root", "group":"root", "modifiedTime":"2026-06-01T07:59:46.742410856Z"}, {"name":"sbin", "type":"FILE_TYPE_DIRECTORY", "path":"/sbin", "size":"8", "mode":493, "permissions":"Lrwxrwxrwx", "owner":"root", "group":"root", "modifiedTime":"2026-05-18T00:00:00Z", "symlinkTarget":"/usr/sbin"}, {"name":"srv", "type":"FILE_TYPE_DIRECTORY", "path":"/srv", "size":"4096", "mode":493, "permissions":"drwxr-xr-x", "owner":"root", "group":"root", "modifiedTime":"2026-05-18T00:00:00Z"}, {"name":"sys", "type":"FILE_TYPE_DIRECTORY", "path":"/sys", "mode":365, "permissions":"dr-xr-xr-x", "owner":"root", "group":"root", "modifiedTime":"2026-06-01T07:59:46.671390630Z"}, {"name":"tmp", "type":"FILE_TYPE_DIRECTORY", "path":"/tmp", "size":"4096", "mode":511, "permissions":"dtrwxrwxrwx", "owner":"root", "group":"root", "modifiedTime":"2026-05-18T00:00:00Z"}, {"name":"usr", "type":"FILE_TYPE_DIRECTORY", "path":"/usr", "size":"4096", "mode":493, "permissions":"drwxr-xr-x", "owner":"root", "group":"root", "modifiedTime":"2026-05-18T00:00:00Z"}, {"name":"var", "type":"FILE_TYPE_DIRECTORY", "path":"/var", "size":"4096", "mode":493, "permissions":"drwxr-xr-x", "owner":"root", "group":"root", "modifiedTime":"2026-05-18T00:00:00Z"}]}%

Download a file

curl -i --request GET --get \
  --data-urlencode "path=/etc/hosts" \
  http://localhost:49983/files
  
HTTP/1.1 200 OK
Accept-Ranges: bytes
Content-Disposition: inline; filename=hosts
Content-Length: 172
Content-Type: text/plain; charset=utf-8
Last-Modified: Mon, 01 Jun 2026 07:59:46 GMT
Vary: Accept-Encoding
Date: Mon, 01 Jun 2026 08:27:59 GMT

127.0.0.1	localhost
::1	localhost ip6-localhost ip6-loopback
fe00::	ip6-localnet
ff00::	ip6-mcastprefix
ff02::1	ip6-allnodes
ff02::2	ip6-allrouters
172.17.0.2	a3c723dfcd0a

process API

start process：

(printf "\x00\x00\x00\x00\x2a" && printf '{"process":{"cmd":"sleep","args":["300"]}}') | curl -i --no-buffer --request POST \
  --url 'http://localhost:49983/process.Process/Start' \
  --header 'Content-Type: application/connect+json' \
  --data-binary @- \
  --output output.bin

List process：

启动 process 之后，在另外一个终端中操作：

# 1. 看看 Docker 容器里有没有这个 sleep 300 现行
docker exec e2b-base-test ps aux

# 2. 看看 envd 内部的 List 注册表有没有抓到它
curl -i --request POST \
  --url 'http://localhost:49983/process.Process/List' \
  --header 'Content-Type: application/json' \
  --data '{}'

init 内部接口

设置环境变量

先通过 init 接口设置环境变量 AI_PROVIDER 和 SANDBOX_STAGE：

 curl -i --request POST \
  --url 'http://localhost:49983/init' \
  --header 'Content-Type: application/json' \
  --data '{
    "envVars": {
      "AI_PROVIDER": "NacreAgent2",
      "SANDBOX_STAGE": "Development2"
    }
  }'
  
  
HTTP/1.1 204 No Content
Cache-Control: no-store
Vary: Origin
Date: Mon, 01 Jun 2026 09:33:02 GMT

启动进程，这个进程通过 env 命个令打印传递给它的环境变量：

(printf "\x00\x00\x00\x00\x23" && printf '{"process":{"cmd":"env","args":[]}}') | curl -i --no-buffer --request POST \
  --url 'http://localhost:49983/process.Process/Start' \
  --header 'Content-Type: application/connect+json' \
  --data-binary @- \
  --output init_env.bin
  
  
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   419    0   379  100    40   115k  12488 --:--:-- --:--:-- --:--:--  136k

strings init_env.bin 查看输出：

strings init_env.bin


HTTP/1.1 200 OK
Connect-Accept-Encoding: gzip
Content-Type: application/connect+json
Vary: Origin
Date: Mon, 01 Jun 2026 09:35:01 GMT
Transfer-Encoding: chunked
{"event":{"start":{"pid":62}}}
{"event":{"data":{"stdout":"RTJCX1NBTkRCT1g9ZmFsc2UKVVNFUj1yb290CkhPTUU9L3Jvb3QKTE9HTkFNRT1yb290CkFJX1BST1ZJREVSPU5hY3JlQWdlbnQKUEFUSD0vdXNyL2xvY2FsL3NiaW46L3Vzci9sb2NhbC9iaW46L3Vzci9zYmluOi91c3IvYmluOi9zYmluOi9iaW4KU0FOREJPWF9TVEFHRT1EZXZlbG9wbWVudApQV0Q9L3Jvb3QK"}}}
;{"event":{"end":{"exited":true, "status":"exit status 0"}}}

把 base64 的数据打印出来

echo "RTJCX1NBTkRCT1g9ZmFsc2UKVVNFUj1yb290CkhPTUU9L3Jvb3QKTE9HTkFNRT1yb290CkFJX1BST1ZJREVSPU5hY3JlQWdlbnQKUEFUSD0vdXNyL2xvY2FsL3NiaW46L3Vzci9sb2NhbC9iaW46L3Vzci9zYmluOi91c3IvYmluOi9zYmluOi9iaW4KU0FOREJPWF9TVEFHRT1EZXZlbG9wbWVudApQV0Q9L3Jvb3QK" | base64 -d

这是 env 命令的输出：

E2B_SANDBOX=false
USER=root
HOME=/root
LOGNAME=root
AI_PROVIDER=NacreAgent
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
SANDBOX_STAGE=Development
PWD=/root

之前设置的 “AI_PROVIDER”: “NacreAgent” 和 “SANDBOX_STAGE”: “Development” 被正确的传递到新启动的进程了。验证OK！

也可以简单的直接调用 envd 的接口查看环境变量：

curl --request GET --url 'http://localhost:49983/envs' 

{"AI_PROVIDER":"NacreAgent","E2B_SANDBOX":"false","SANDBOX_STAGE":"Development"}

设置 access token

通过 init 接口设置 access token：

 curl -i --request POST \
  --url 'http://localhost:49983/init' \
  --header 'Content-Type: application/json' \
  --data '{
  	"accessToken": "your-secret-token",
    "envVars": {
      "AI_PROVIDER": "NacreAgent2",
      "SANDBOX_STAGE": "Development2"
    }
  }'

code interpreter 镜像

TODO