Create a reusable environment template that stores container, dependency, network, initial file, and skill configuration.
Endpoint
POST /agents/environments/templates
Returns 201 and the complete environment template. The request body can be empty; in that case the template is created with default configuration.
Request bodynamestring / null (optional)Template namepackages object (optional)Packages grouped by npm, python, and system; all three groups default to empty arraysenv object<string,string> (optional)Environment variables; names must match [A-Za-z_][A-Za-z0-9_]*, cannot be PATH, and cannot start with a server-reserved prefix; values cannot contain NULsetup_commands array (optional)Setup commands executed in order. Each item requires command and accepts an optional cwd; cwd defaults to /workspacenetwork object (optional)Network policy, defaults to enabled; blocked_domains is not accepteddesktop object (optional)Desktop settings; only enabled=false is accepted, and enabled=true returns 400capability_directories array<string> (optional)Capability discovery directories, defaults to []skills array (optional)Skill configuration, fixed as skill_referenceplugins array (optional)Plugin configuration; only an empty array is supported, and non-empty arrays return 400files array (optional)Initial file configuration, fixed as file_id
Properties
packages python array<string> (optional)Python packagessystem array<string> (optional)System packagesnpm array<string> (optional)npm packages
setup_commands command string (optional)Setup commandcwd string (optional)Working directory, defaults to /workspace
network access string (optional)Network access mode, enabled, disabled, or restrictedallowed_domains array<string> (optional)Allowed domains when access=restricted
desktop enabled boolean (optional)Whether the desktop is enabledenv or setup_commands. files is always file_id, and skills is always skill_reference. | Request example |
Response fieldsidstringEnvironment template IDobject stringEnvironment template object type, fixed as agent.environment.templatename string / nullTemplate namecreated_at integerCreation time in Unix secondsupdated_at integerLast update time in Unix secondspackages objectPackages with python, system, and npmnetwork objectNetwork policy with access and allowed_domainsdesktop objectDesktop settings with enabledcapability_directories array<string>Capability discovery directoriesskills arraySkill configuration with type, skill_id, and versionplugins arraySafe plugin metadata. Contains type, name, and description; currently an empty arrayfiles arrayInitial file configuration; each item contains type, path, and file_id | Response example |
Error codes
| HTTP status | Error type / code | Solution |
|---|---|---|
400 | invalid_request_error / invalid_request_error | Fix the request body as described for each field |
400 | invalid_request_error / invalid_request_error | desktop.enabled=true, non-empty plugins, and network.blocked_domains are rejected; adjust the field accordingly |
401 | authentication_error / invalid_api_key | Send a valid Authorization: Bearer $DASHSCOPE_API_KEY header |
500 | server_error / server_error | Retry later. If it keeps failing, submit a ticket with x-request-id |