Official Base Image and the Server SDK

Status: v2 (reviewed; see fine-grained-capabilities-review.md) — reviewed together with the fine-grained capability design in fine-grained-capabilities-review.md. Product requirement: all template builds should be based on the Alibaba Cloud Agent Sandbox (FC Agent Sandbox) base image.

Update. The Python client no longer builds images: Image, DockerBuilder, Sandbox.deploy and agent_sandbox.api.base_image were removed. The base-image contract in section 3, the lint and the Dockerfile scaffold are owned by the abx CLI (abx template init|build|deploy). Sections 4, 5, 7 and 8 describe what remains in this repository.

1. What the base image is (evidence)

Sources: repository research (.agents/evidence/research/2026-09-04-fc-claude-code-image-inspection.md, ...-fc-sandbox-official-docs.md), and the official doc page Build a custom image template (fetched while writing this design; it currently cites tag v0.0.49, older notes cite v0.0.44).

2. Decision

Server-SDK design work is warranted. Template builds default to the official base image through scaffolding, a documented contract, helpers and linting — not by silently changing the behaviour of existing APIs.

Reasoning:

1. Correctness, not taste. create_official_template(envd_inject=False) is our default path: it only yields a working sandbox if the image already contains envd. A template built FROM ubuntu:22.04 has no envd unless the platform builder injects it. Basing on the official image makes the default path valid and lets the platform skip the copy + envdInject builder function (faster, cheaper, fewer moving parts, envd/gateway versions are the platform's tested ones).
2. The server SDK has to live somewhere. Layering agent-sandbox-server onto the official image gives a well-defined target: known PID 1, known user/HOME (default ABX_SERVER_BASE_DIR=/home/user matches), known ports (49983/5000 taken -> 9000/9001 free).
3. Do not break unconfigured callers. The CLI still accepts any Dockerfile. A non-official base is an advisory warning, not an error.

3. The contract (what a Dockerfile layered on the base image can rely on)

Documented in server-api.md and enforced by the CLI's template lint:

4. What gets implemented

server-sdk

• agent-sandbox-server console script and python -m agent_sandbox.server (__main__.py): serve (default; --host --port --commands <file-or-module> --policy <json> --preset <name> --base-dir), healthcheck (HTTP GET /health, exit code 0/1, for HEALTHCHECK and ready_cmd), check-config (validate + lint a policy, print effective endpoint table), version. --commands imports a user module so its registry.command(...)/table.route(...) side effects register (what commands.py did with start()), then serves — a template needs no bespoke commands.py boilerplate.
• agent_sandbox.server.contract constants (ports, paths, env-var names) shared by CLI/server.
• Policy auto-load (/etc/agent-sandbox/server-policy.json).
• pyproject.toml: [project.scripts] agent-sandbox-server = "agent_sandbox.server.__main__:main".

client-sdk

• Sandbox.start_server(...) (remote start + readiness) and the Sandbox.server client.
• SandboxTemplate.server (structurally validated policy block). A declarative SandboxTemplate.base_image field was considered and not added: the Dockerfile is the single source of truth for the base, and the lint (B001) reads it from there.

Not implemented (justified)

• No bundling of the server wheel in a custom base image: the wheel injection already covers the "installed from PyPI" and "dev checkout" cases and keeps lockstep versions.
• No second HTTP gateway/proxy: the platform gateway on 5000 already routes {port}-{sandbox} hosts.

5. CLI-side changes (recorded in cli-followups.md)

Node scaffold abx template init (FROM official base, scaffold per section 3); deploy path (wheel injection, envd_inject auto-choice, start_cmd/ready_cmd); template.yaml server: compile; AI template-guide prompt (must start FROM the official base, never override ENTRYPOINT, use agent-sandbox-server serve).

6. Open questions (cannot be settled from repo/docs)

1. Does the gateway honour a Dockerfile CMD or only the platform start_command? (we avoid CMD.)
2. Is /home/user + user user guaranteed for the plain base image (documented for claude-code)?
3. Exact default tag: docs say v0.0.49; we expose ABX_BASE_IMAGE_TAG and a constant so it is one line to bump.
4. Does the platform tolerate an already-envd-containing non-official image with envdInject on?

7. Changes after review (Draft v1 -> v2)

• The claim that the gateway forwards Authorization is unverified (OQ-3 in the review log): the server accepts both X-Access-Token and Authorization: Bearer, so either gateway behaviour works.
• healthcheck uses only urllib.request against 127.0.0.1 (2 s timeout, exit code 0/1) so it can serve as a Docker HEALTHCHECK/ready_cmd without heavy imports.
• Console script name agent-sandbox-server verified not to clash with abx.

8. Implementation status

Implemented here: agent-sandbox-server console script (serve, healthcheck, check-config, version), agent_sandbox.server.contract, and the client's Sandbox.server / server_at() / start_server(). Tests: tests/test_api/server_e2e/test_sandbox_server_helpers.py, server-sdk/tests/test_server/test_cli_main.py. The base-image helpers, the lint (B001-B005) and the scaffold moved to the CLI. Exact CLI-side changes: cli-followups.md.