WebsiteRegistry
/
中文

Publish guide

View on GitHub ↗

Publish guide

The registry lists two kinds of entries: templates and providers. Both arrive by pull request to the matching repository. After the merge this site refreshes within an hour, and the SDK's update check reads the same data.

Publish a template

Templates live in awesome-templates.

  1. Create a kebab-case directory at the repository root. The directory name, name in template.yaml and path in the index are the same string.
  2. Add template.yaml, Dockerfile, commands.py, e2e_test.py and README.md.
  3. Add one entry under the right section of awesome-templates.yaml: name, description, repo, path, tags, author, capabilities, status.
  4. From the repository root run python3 scripts/run_local_e2e.py. Every template with a commands.py must pass.

status is official, community or experimental. Community submissions start as community. Never commit secrets: list key names in template.yaml env with empty values.

The README has to say what the template is, how to deploy it and how to run its e2e. On Express, deploy the directory. The platform id is TemplateID; --alias also accepts that name at create time. base may be an image string. A directory with commands.py and no generation is published as generation 2. The in-image package is agent-sandbox-server. It is not on PyPI yet. Do not pip install agent-sandbox.

abx template deploy ./<name> -y --alias <name>
abx create --template <name>
python3 scripts/run_local_e2e.py

Catalog providers do not declare templates.build, so abx template deploy --provider <id> returns E8004 and does not register the directory on OpenSandbox, E2B, CubeSandbox, or the container edition. Provider-side deploy is planned: Provider template deploy.

Publish a provider

Providers live in awesome-providers. A provider is a directory: abx-provider.toml plus the program its runtime needs. Do not put it in the SDK or CLI repository.

my-cloud/
  abx-provider.toml
  provider.mjs         # only when kind = "node"
  README.md

Pick a runtime. All of them install under ~/.abx/providers/<id> and work from the CLI and every SDK, because the host that loads a provider is the Node.js CLI (SDKs reach a node or exec provider through the local engine, abx provider engine serve). The four providers in this catalog are node. Install abx 0.3.0 with curl -fsSL https://raw.githubusercontent.com/Alibaba-Agent-Sandbox/agent-sandbox/main/install.sh | sh (Windows: irm https://raw.githubusercontent.com/Alibaba-Agent-Sandbox/agent-sandbox/main/install.ps1 | iex), then abx provider install alibaba-agent-sandbox/awesome-providers//<id> --allow-unpinned --yes. The Python form python -m agent_sandbox.providers install registry:<id> --yes reads this site's index; abx has no registry: source. agent-sandbox-client 0.3.0 is not on PyPI yet (pip install agent-sandbox-client is coming). Until then: pip install "agent-sandbox-server @ git+https://github.com/Alibaba-Agent-Sandbox/python-sdk@35da216a300f1e2e84254a1cf4b4a7ea98681505#subdirectory=server-sdk" "agent-sandbox-client @ git+https://github.com/Alibaba-Agent-Sandbox/python-sdk@35da216a300f1e2e84254a1cf4b4a7ea98681505#subdirectory=client-sdk".

Kind What you write When
rest Manifest only The backend speaks E2B-shaped HTTP
exec Manifest plus a process The API is not E2B-shaped. Any language; the process speaks EPP/1
node Manifest plus provider.mjs The backend is E2B-shaped but needs a tweak (a proxy dial, an optional token, different paths). An ES module loaded in the CLI's Node host

Manifest essentials:

  • id matches ^[a-z][a-z0-9]*(-[a-z0-9]+)*$, length 2 to 40, and avoids reserved ids and the abx- and alicloud- prefixes.
  • [features] supported lists only what you really implement. An undeclared capability returns E8004 before the call, and the capability matrix on this site is built from it.
  • [security] network lists the hosts you contact.
  • The secret field is api_key; the environment variable is derived from the id. Never read the Express key ABX_SANDBOX_API_KEY.

Then add one row { "id", "version", "url" } to index.json. The full fields and an example are in the provider docs.

Review bar

  • Say what you verified. If there was no real backend to test against, say so in the README.
  • Every declared capability is implemented, and nothing undeclared is quietly supported.
  • No hard-coded secrets and no code that runs at install time.
  • Raise version on every update. If the content changes within a version the package sha256 changes and the update check will flag it.

After you submit

Once merged into main, the repository notifies the registry to rebuild. The site also pulls on its own every hour. Confirm with:

curl -s https://registry.agent-sandbox.cn/providers/index.json