OpenSandbox Go SDK 完整实战指南Lifecycle、Execd 与 Egress 三大 API 的统一客户端【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox导读本文是一份基于 OpenSandbox 仓库 sdks/sandbox/go/README.md 及其 Go SDK 源码 的实战技术指南。OpenSandbox 是一个面向 AI Agent 的安全、快速、可扩展的沙箱运行时其 Go SDK 用一套统一的客户端封装了 Lifecycle沙箱生命周期管理、Execd沙箱内命令执行与文件操作和 Egress出站网络策略与凭据保险箱三大 OpenAPI。读完本文你将掌握从安装、连接配置、创建/查询/释放沙箱到流式执行命令、文件传输、动态修改出站网络策略、使用 Credential Vault 注入凭据的完整能力并理解底层 SSE 流式协议、自动重试、TLS 安全策略与沙箱池释放的实现细节。一、SDK 概览与安装OpenSandbox Go SDK 位于仓库的 sdks/sandbox/go 目录是一个覆盖三份 OpenAPI 规范specs/sandbox-lifecycle.yml、specs/execd-api.yaml、specs/egress-api.yaml的完整客户端库Lifecycle—— 创建、管理、销毁沙箱实例对应 lifecycle.go 与 manager.goExecd—— 在沙箱内执行命令、管理文件、监控系统指标对应 execd.goEgress—— 在运行时查看与修改沙箱的出站网络策略、管理 Credential Vault对应 egress.go。SDK 要求Go 1.20安装方式go get github.com/alibaba/OpenSandbox/sdks/sandbox/go当前 SDK 版本号为1.0.5见 constants.go 中的Version常量并会通过User-Agent: OpenSandbox-Go-SDK/1.0.5上报给服务端。SDK 采用 Apache 2.0 许可。二、三个客户端与连接配置SDK 提供三个职责单一的客户端分别面向三大 API客户端构造函数认证头默认端口/端点LifecycleClientNewLifecycleClient(baseURL, apiKey string, opts ...Option)OPEN-SANDBOX-API-KEY服务端 APIbaseURL 需带/v1前缀ExecdClientNewExecdClient(baseURL, accessToken string, opts ...Option)X-EXECD-ACCESS-TOKEN沙箱内 execd 服务默认44772EgressClientNewEgressClient(baseURL, authToken string, opts ...Option)OPENSANDBOX-EGRESS-AUTH沙箱内 egress sidecar默认18080三个客户端的认证头常量分别定义在 lifecycle.go、execd.go 与 egress.go 中execd 与 egress 的默认端口定义在 constants.go。2.1 使用 ConnectionConfig 统一配置除了直接调用构造函数SDK 还提供ConnectionConfigconfig.go作为更高层的连接配置入口字段支持环境变量回退与默认值字段说明回退顺序Domain服务端地址如localhost:8080OPEN_SANDBOX_DOMAIN→DefaultDomainlocalhost:8080Protocolhttp或httpsOPEN_SANDBOX_PROTOCOL→DefaultProtocolhttpAPIKey认证令牌OPEN_SANDBOX_API_KEYUseServerProxy让 execd/egress 请求经由 sandbox server 代理转发而非直连沙箱端点—RequestTimeout非流式 HTTP 请求超时0 表示不设超时DefaultRequestTimeout30sHeaders追加到所有请求的自定义 HTTP 头—HTTPClient/Transport自定义 HTTP 客户端或连接池配置SDK 默认创建AuthHeader覆盖生命周期 API 的认证头名默认OPEN-SANDBOX-API-KEY代理部署可改用X-API-Key—Retry指数退避自动重试策略详见下文错误处理与重试默认不重试EndpointHostRewrite将服务端返回的 endpoint URL 主机名重写例如 Docker 部署下把不可达的host.docker.internal映射为localhost—EndpointCacheTTL/EndpointCacheSize端点缓存有效期默认 600s与容量默认 1024—EndpointCacheDisabled完全禁用端点缓存—DisableMetrics关闭 SDK 遥测如sandbox.create延迟上报也可用环境变量OPENSANDBOX_DISABLE_METRICS1—ConnectionConfig的关键行为见 config.goGetBaseURL()会拼出protocol://domain如果Domain已带http:///https://前缀则原样使用并自动去除末尾/lifecycleClient()会自动追加 API 版本前缀/v1APIVersion常量定义于 constants.go因为NewLifecycleClient要求 baseURL 包含版本前缀execdClient()/egressClient()会把生命周期GetEndpoint返回的所有头认证令牌、路由提示、粘性会话键等原样转发到后续每个请求。2.2 客户端选项Option所有构造函数都接受变长的Option函数例如client : opensandbox.NewLifecycleClient(url, key, opensandbox.WithHTTPClient(myHTTPClient), ) client : opensandbox.NewExecdClient(url, token, opensandbox.WithTimeout(60 * time.Second), )SDK 创建的 HTTP 客户端默认强制NIST 2030 最低 TLS 证书强度RSA ≥ 2048、EC ≥ 224、DSA P ≥ 2048 / Q ≥ 224、hash ≥ 224。若必须与旧端点互通可在TransportConfig中设置AllowWeakServerCertKeyLengths: true对应实现见 transport.go 与 crypto_policy.go。默认的DefaultTransportConfig()对连接池做了针对多沙箱并发场景的调优MaxIdleConns100、MaxIdleConnsPerHost10、IdleConnTimeout30s。其中IdleConnTimeout刻意低于常见负载均衡器约 60s 的空闲超时避免 SDK 复用到已被 LB 静默断开未发 FIN的 keep-alive 连接而导致请求挂起见 transport.go 的注释说明。三、Lifecycle创建与管理沙箱Lifecycle API 由 lifecycle.go 实现是管理沙箱整个生命周期的核心入口。完整 API 列表方法说明CreateSandbox(ctx, req)从容器镜像创建沙箱GetSandbox(ctx, id)按 ID 查询沙箱详情ListSandboxes(ctx, opts)带过滤与分页的沙箱列表DeleteSandbox(ctx, id)删除沙箱PauseSandbox(ctx, id)/ResumeSandbox(ctx, id)暂停 / 恢复沙箱RenewExpiration(ctx, id, expiresAt)延长沙箱绝对过期时间GetEndpoint(ctx, sandboxID, port, useServerProxy)获取沙箱端口的公网访问端点GetSignedEndpoint(ctx, sandboxID, port, expires)获取携带 OSEP-0011 签名路由令牌的带签名的端点 URLPatchSandboxMetadata(ctx, id, patch)增量修改沙箱元数据ListSnapshots/CreateSnapshot/GetSnapshot/DeleteSnapshot沙箱快照管理3.1 创建沙箱package main import ( context fmt log github.com/alibaba/OpenSandbox/sdks/sandbox/go ) func main() { ctx : context.Background() lc : opensandbox.NewLifecycleClient(http://localhost:8080/v1, your-api-key) sbx, err : lc.CreateSandbox(ctx, opensandbox.CreateSandboxRequest{ Image: opensandbox.ImageSpec{URI: python:3.12}, Entrypoint: []string{/bin/sh}, ResourceLimits: opensandbox.ResourceLimits{ cpu: 500m, memory: 512Mi, }, }) if err ! nil { log.Fatal(err) } fmt.Printf(Created sandbox: %s (state: %s)\n, sbx.ID, sbx.Status.State) sbx, err lc.GetSandbox(ctx, sbx.ID) if err ! nil { log.Fatal(err) } list, err : lc.ListSandboxes(ctx, opensandbox.ListOptions{ States: []opensandbox.SandboxState{opensandbox.StateRunning}, PageSize: 10, }) if err ! nil { log.Fatal(err) } fmt.Printf(Running sandboxes: %d\n, list.Pagination.TotalItems) _ lc.PauseSandbox(ctx, sbx.ID) _ lc.ResumeSandbox(ctx, sbx.ID) _ lc.DeleteSandbox(ctx, sbx.ID) }从 types.go 看CreateSandboxRequest支持丰富的创建参数除Image、Entrypoint、ResourceLimits外还包括SnapshotID—— 从快照恢复创建Timeout—— 沙箱 TTL秒默认DefaultTimeoutSeconds 60010 分钟ResourceRequests—— 与ResourceLimits同结构的资源请求Env—— 环境变量SecureAccess—— 安全访问开关Metadata/Extensions—— 键值元数据与扩展字段Lifecycle—— 生命周期钩子PreStart前置命令 Periodic周期性命令见 types.goNetworkPolicy—— 出站网络策略见第五节CredentialProxy—— Credential Vault 透明代理开关见第六节Volumes—— 存储挂载支持Host路径绑定、PVC命名卷与阿里云OSSFS三种后端types.goPlatform—— 平台约束osarch可指定linux/windows、amd64/arm64types.go。资源限制是map[string]string形式的键值对常见键cpu如500m、memory如512Mi、gpu如1。SDK 内置的默认资源限制为cpu: 1、memory: 2Gi默认 entrypoint 为tail -f /dev/null以保持沙箱存活供交互使用constants.go。3.2 沙箱状态机与列表过滤沙箱状态定义在 types.goPending→Running→Pausing→Paused→Stopping→Terminated另有失败态Failed。ListSandboxes的ListOptionslifecycle.go支持States—— 按生命周期状态过滤多值采用 OR 逻辑Metadata—— 按键值元数据过滤采用 AND 逻辑编码进metadata查询参数Page默认 11 起算与PageSize默认 20—— 分页控制。列表响应中的PaginationInfotypes.go提供TotalItems、TotalPages、HasNextPage等分页元数据便于实现游标式的拉取循环。3.3 端点解析与缓存沙箱内的服务需要通过GetEndpoint暴露为公网可访问端点。从源码看lifecycle.goGetEndpoint做了三层优化LRU TTL 缓存默认容量 1024、有效期 600ssingleflight 去重GetOrFetch保证同一(sandboxID, port, useServerProxy)键的并发请求只触发一次服务端调用且共享抓取使用后台 context避免某个调用方的 deadline 取消所有等待者可通过useServerProxy参数请求经由服务端代理转发。GetSignedEndpoint(ctx, sandboxID, port, expires)则返回内嵌OSEP-0011 签名路由令牌以 Unix 时间戳指定过期秒数的端点 URL用于受限时间窗口的安全访问相关提案见 oseps/0011-secure-access-endpoint.md。四、Execd命令执行、文件操作与指标ExecdClientexecd.go直接连接沙箱内的 execd 服务默认端口 44772提供命令执行、代码执行、文件/目录操作与系统指标四大类能力。4.1 健康检查exec : opensandbox.NewExecdClient(http://localhost:9090, your-execd-token) err : exec.Ping(ctx) // GET /ping4.2 流式执行命令RunCommand使用SSE 流式返回输出事件通过回调处理err : exec.RunCommand(ctx, opensandbox.RunCommandRequest{ Command: echo Hello from sandbox!, Timeout: 30000, }, func(event opensandbox.StreamEvent) error { switch event.Event { case stdout: fmt.Print(event.Data) case stderr: fmt.Fprintf(os.Stderr, %s, event.Data) case execution_complete: fmt.Println(\n[done]) } return nil })RunCommandRequesttypes.go的字段很灵活Command与Argv二选一前者是 shell 文本后者是字面参数数组要求下标 0 为非空可执行文件且元素不得含 NUL由服务端校验Cwd—— 工作目录Background—— 后台执行Timeout—— 超时毫秒UID/GID—— 以指定用户/组身份运行Envs—— 追加环境变量。4.3 bash 会话Session需要保持 shell 状态如cd后连续执行时使用会话模式方法说明CreateSession(ctx)创建 bash 会话返回session_idRunInSession(ctx, sessionID, req, handler)在会话内执行命令SSE 流式DeleteSession(ctx, sessionID)删除会话4.4 后台命令的状态与日志后台命令Background: true可通过GetCommandStatus(ctx, commandID)轮询状态返回running、exit_code等见 types.go并通过GetCommandLogs(ctx, commandID, cursor)增量拉取输出cursor传-1或0拉全量日志服务端通过EXECD-COMMANDS-TAIL-CURSOR响应头返回新的游标实现边执行边追日志实现见 execd.go。4.5 代码执行上下文Code Context面向代码解释器类场景SDK 支持带状态的语言上下文CreateContext(ctx, {Language})创建上下文ExecuteCode(ctx, req, handler)在上下文中流式执行代码InterruptCode(ctx, sessionID)中断执行ListContexts/GetContext/DeleteContext/DeleteContextsByLanguage管理上下文生命周期。4.6 文件与目录操作类别方法说明查询GetFileInfo(ctx, path)文件元数据类型、大小、属主、权限位等搜索SearchFiles(ctx, dir, pattern)按 glob 模式搜索文件列目录ListDirectory(ctx, path)立即子项服务端默认深度列目录ListDirectoryWithDepth(ctx, path, depth)列目录至指定深度0返回空负数被服务端拒绝删除DeleteFiles(ctx, paths)/DeleteDirectory(ctx, path)删文件 / 递归删目录权限SetPermissions(ctx, req)批量修改属主、属组与模式位移动MoveFiles(ctx, req)批量移动/重命名替换ReplaceInFiles(ctx, req)批量文本替换ReplaceInFilesDetailed返回每个文件的替换计数建目录CreateDirectory(ctx, path, mode)mkdir -p语义mode 为十进制八进制数字如755可用OctalMode(os.FileMode)转换上传UploadFile(ctx, file, opts)/UploadFiles(ctx, entries)单文件 / 多文件 multipart 上传可携带元数据目标路径、属主、模式下载DownloadFile(ctx, remotePath, rangeHeader, opts...)下载文件支持Range头与基于行的Offset/Limit读取其中多文件上传UploadFiles在一个 multipart 请求中为每个文件同时携带 JSON 元数据execd.go 使用io.Pipe流式构造请求体避免大文件整体驻留内存。下载DownloadFile返回io.ReadCloser调用方负责关闭且支持 HTTPRange头如bytes0-1023实现断点续传。4.7 系统指标GetMetrics(ctx)一次性获取资源指标CPU 核数/使用率、内存总量/已用 MB、时间戳见 types.goWatchMetrics(ctx, handler)通过 SSE 约每秒推送一次实时指标直到 context 取消。五、SSE 流式协议原理凡是流式输出的方法RunCommand、ExecuteCode、RunInSession、WatchMetrics都接受统一的事件回调签名type EventHandler func(event StreamEvent) errorStreamEventstreaming.go包含三个字段Event—— 事件类型如stdout、stderr、result、execution_complete对于 NDJSON 流会自动从 JSON 的type字段提取Data—— 原始事件负载NDJSON 流下为 JSON 字符串ID—— 可选的服务器事件标识。回调返回非 nil error 即可提前终止流处理。从 streaming.go 的实现看SDK 的 SSE 解析器有四个值得注意的设计大负载支持scanner 缓冲从默认 64KiB 提升到 4MiB可承载大型输出数据行NDJSON 兼容不以data:前缀开头、直接以{起始的裸 JSON 行也被识别为事件并提取type字段填充Event让下游switch event.Event的逻辑在 SSE 与 NDJSON 两种协议下保持一致标准 SSE 语义空行表示事件块结束多个data:行以换行拼接event:/id:字段分别填充Event/ID注释行:开头被忽略context 感知每次扫描前检查ctx.Done()支持中途取消空流一个事件都没有会被判定为错误返回。六、Egress出站网络策略与凭据保险箱EgressClientegress.go连接沙箱内的 egress sidecar默认端口 18080负责两件事出站网络策略的运行时查看与修改以及 Credential Vault 凭据注入。6.1 查看与修改出站策略egress : opensandbox.NewEgressClient(http://localhost:18080, your-egress-token) policy, err : egress.GetPolicy(ctx) fmt.Printf(Mode: %s, Default: %s\n, policy.Mode, policy.Policy.DefaultAction) updated, err : egress.PatchPolicy(ctx, []opensandbox.NetworkRule{ {Action: allow, Target: api.example.com}, })GetPolicy返回PolicyStatusResponsetypes.go包含 sidecar 状态、模式Mode、执行模式EnforcementMode与当前策略PatchPolicy将规则合并进当前策略已有规则除非被覆盖否则保留DeletePolicy(ctx, targets)按 FQDN 或通配域名幂等地删除规则保留当前defaultActionegress.go。网络策略结构为NetworkPolicy{ DefaultAction, Egress []NetworkRule }每条NetworkRule是一个actionallow/denytarget目标域名对types.go。更细的 FQDN 控制模型可参考 oseps/0001-fqdn-based-egress-control.md 与组件文档 docs/components/egress.md。6.2 Credential Vault凭据安全注入Credential Vault 由 egress sidecar 注入出站凭据使真实密钥永不进入沙箱的环境变量、命令、文件与日志。用法分两步第一步创建沙箱时启用CredentialProxyCredentialProxyConfig{Enabled: true}并设置默认拒绝的出站策略sandbox, err : manager.Create(ctx, opensandbox.SandboxCreateOptions{ Image: python:3.11, NetworkPolicy: opensandbox.NetworkPolicy{ DefaultAction: deny, Egress: []opensandbox.NetworkRule{ {Action: allow, Target: api.example.com}, }, }, CredentialProxy: opensandbox.CredentialProxyConfig{Enabled: true}, }) if err ! nil { return err }第二步通过沙箱 helper 或EgressClient写入凭据与绑定规则_, err sandbox.CreateCredentialVault(ctx, opensandbox.CredentialVaultCreateRequest{ Credentials: []opensandbox.Credential{ { Name: api-token, Source: opensandbox.InlineCredentialSource{ Type: opensandbox.CredentialSourceInline, Value: token, }, }, }, Bindings: []opensandbox.CredentialBinding{ { Name: api-token, Match: opensandbox.CredentialMatch{ Schemes: []opensandbox.CredentialScheme{opensandbox.CredentialSchemeHTTPS}, Ports: []int{443}, Hosts: []string{api.example.com}, Paths: []string{/v1/*}, }, Auth: opensandbox.CredentialAuth{ Type: opensandbox.CredentialAuthAPIKey, Name: x-api-key, Credential: api-token, }, }, }, })从 types.go 看Credential Vault 的模型设计有几个要点凭据源目前仅支持inline类型CredentialSourceInline为只写模型——写入的值绝不会从 Vault 状态端点返回MarshalJSON还会自动补全类型调用方可以只写InlineCredentialSource{Value: secret}匹配规则CredentialMatch按Schemeshttps/http、Hosts、Methods、Paths匹配出站请求。注意Ports已标记废弃端口由 Schemes 推导https→443、http→80注入方式CredentialAuth支持五种类型types.gobearer、basic、apiKey、customHeaders、passthroughcustomHeaders配合Headers列表逐项注入自定义头另有Substitutions可对 path/query/header/body 做字面量占位符替换原子变更PatchCredentialVault通过CredentialVaultPatchRequest{ExpectedRevision, Credentials.Add/Replace/Delete, Bindings.Add/Replace/Delete}原子地增删改ExpectedRevision用作乐观并发守卫脱敏读取所有读取端点GetCredentialVault、ListCredentialVaultCredentials等返回的都是不含明文值与凭据引用的元数据CredentialMetadata、CredentialBindingMetadata。完整的 EgressClient Vault 方法集见 egress.go包括CreateCredentialVault、GetCredentialVault、PatchCredentialVault、DeleteCredentialVault及四个元数据查询方法。认证类型、绑定指导与 Git/curl 示例详见 docs/guides/credential-vault.md设计提案见 oseps/0012-credential-vault.md 与 oseps/0023-credential-bound-tls-interception.md。七、错误处理与自动重试非 2xx 响应统一返回*opensandbox.APIError_, err : lc.GetSandbox(ctx, nonexistent) if apiErr, ok : err.(*opensandbox.APIError); ok { fmt.Printf(HTTP %d: %s — %s\n, apiErr.StatusCode, apiErr.Response.Code, apiErr.Response.Message) }APIErrortypes.go除StatusCode、Response{Code, Message}外还携带RequestIDError()消息中会附带request_id与RetryAfter从响应Retry-After头解析出的建议等待时长。SDK 提供内置的指数退避重试retry.goclient : opensandbox.NewLifecycleClient(url, key, opensandbox.WithRetry(opensandbox.DefaultRetryConfig()), )DefaultRetryConfig()retry.go的默认策略为最多 3 次重试、初始退避 500ms、倍数 2.0、上限 30s、抖动 ±25%可重试状态码为429/502/503/504。重试机制有三个实现细节可重试判定isTransientError*APIError按状态码分类429 限流、502/503/504 基础设施故障为瞬时400/401/403/404/409/422 等为永久网络层net.Error也被视为瞬时错误抖动为避免惊群退避时长乘以(1 ± Jitter)随机因子尊重 Retry-After若服务端返回Retry-After且长于计算出的退避时间则取其作为等待时长重试等待期间响应 context 取消retrySleep保证优雅退出。八、高级用法SandboxManager 与沙箱池释放8.1 SandboxManagerSandboxManagermanager.go是一个无需连接具体沙箱的管理器由NewSandboxManager(config ConnectionConfig)创建内部基于config.lifecycleClient()。它提供ListSandboxInfos、GetSandboxInfo、KillSandbox、PauseSandbox/ResumeSandbox、RenewSandbox(ctx, id, duration)从当前时间起延长指定时长、PatchSandboxMetadata以及快照系列的CreateSnapshot/GetSnapshot/ListSnapshots/DeleteSnapshot适合编写批量运维工具。8.2 释放空闲池沙箱对*DefaultSandboxPool而言README 明确给出了两种释放策略ReleaseAllIdle(ctx)保持原始的 fire-and-forget 语义排空所有空闲 ID 并调度 best-effort 删除后立即返回。从 pool.go 的实现看它循环调用StateStore.TryTakeIdle取空闲 ID每个 ID 用独立 goroutine 执行killSandboxBestEffortReleaseAllIdleParallel(ctx, maxWorkers)则对删除并发度设上限并阻塞等待每个已排空 ID 都收到删除尝试后才返回maxWorkers必须为正数否则返回错误。注意其 context 只约束排空阶段——一旦 ID 被排空删除尝试使用独立的超时即使 context 被取消也会执行完毕pool.go。设计上ReleaseAllIdleParallel刻意不加入SandboxPool接口从而保证现有接口实现者的兼容性不受破坏。九、更多资源完整方法签名与类型定义sdks/sandbox/go核心文件 lifecycle.go、execd.go、egress.go、types.go三类 API 的 OpenAPI 规范specs/sandbox-lifecycle.yml、specs/execd-api.yaml、specs/egress-api.yaml服务端实现参考server/opensandbox_serverLifecycle 服务端与 components/execd、components/egressGo 端到端测试示例tests/go沙箱池机制的设计文档docs/guides/client-pool.md 与提案 oseps/0005-client-side-sandbox-pool.md、oseps/0021-scalable-asynchronous-client-side-pool-warmup.md安全访问与凭据注入oseps/0011-secure-access-endpoint.md、docs/guides/credential-vault.md。十、总结OpenSandbox Go SDK 用LifecycleClient、ExecdClient、EgressClient三个客户端完整覆盖了沙箱创建 → 使用 → 释放与入站访问 出站管控的全部环节。其设计亮点包括统一的ConnectionConfig配置与 NIST 2030 TLS 安全基线、SSE/NDJSON 双协议流式事件回调、内置指数退避自动重试、端点 LRUTTL 缓存与 singleflight 去重、以及让真实凭据永不进入沙箱的 Credential Vault 透明代理。结合本仓库源码sdks/sandbox/go/*.go阅读本文可以快速上手并把沙箱生命周期、代码执行、文件操作与出站策略控制嵌入到自己的 Go 应用中。【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考