Decision: Document the template server HTTP API

Status: proposed

Problem

A template generated by the CLI is a Dockerfile plus commands.py plus template.yaml. After deploy, callers only have an HTTP URL (sandbox.network.get_url). The process that answers is agent_sandbox.server, started from commands.py. Users need a spec of the routes that process actually serves, in English and Chinese, next to the template-authoring guide. The design reference is not that caller-facing page, and it is easy to describe a base image as if every template shared one.

Decision

Publish two user guides that describe only the routes registered by the server route modules:

• python-sdk/docs/en/guide/template-server-api.md
• python-sdk/docs/zh/guide/template-server-api.md

Link them from the English and Chinese template-authoring guides and from examples/README.md and examples/README.zh-CN.md. Ship python-sdk/examples/templates/python-hello/call_api.py as a client that takes its base URL from argv or ABX_TEMPLATE_URL and its token from ABX_SERVER_TOKEN, with no credential in the file.

The Dockerfile base image is not settled in this note. A separate review owns provider versus base image. Templates vary the FROM line. The HTTP API does not vary with that image: it is whatever agent_sandbox.server registers when commands.py calls SandboxServer.serve.

API Design

N/A — this decision does not involve API changes. The guides describe the HTTP API the server already serves (GET /health open; GET /capabilities requires X-Access-Token when ABX_SERVER_TOKEN is set; capability groups and their routes; custom @registry.command and @table.route).

Alternatives considered

• Point readers only at docs/en/design/server-api.md — rejected. That page is a design reference. Callers need a guide beside template authoring, with curl and a runnable client, in both languages.
• Pick a base image in the same note — rejected. Provider versus base image belongs to a separate review. This note does not choose one, and the guides say the image varies while the HTTP API does not.

Dependencies

Read-only: agent_sandbox.server route modules and cli/src/agent/template_guide.ts (the latter only as the prompt the generator follows). No Dockerfile change. No server code change.

Test Strategy

call_api.py is a stdlib client meant to run against a local SandboxServer (python call_api.py http://127.0.0.1:9000). It covers GET /health, GET /capabilities, GET /commands, POST /upload, and POST /shell. The guides are documentation; they do not change server behaviour. No unit test asserts prose.

Acceptance criteria

• Both guides describe how the sandbox is reached, ABX_SERVER_TOKEN / X-Access-Token, which routes each capability group turns on, request and response shapes, how a custom command and a custom route show up, and curl for health, list commands, run a command, upload, and download.
• The Chinese guide is a full translation of the English guide.
• call_api.py reads the URL and token from argv / the environment and embeds neither.
• This note stays Status: proposed and does not select a Dockerfile base image.