Docs
⌘K
Templates ›

Set template network

PUT/v1/templates/{id}/network

Sets what a sandbox on the template may reach outside itself, in place of the rule it had. The whole rule is sent each time: an allowlist is replaced, not added to. A sandbox is held to it with its own addresses on top: an open template lets everything out, a blocked one lets out only its own addresses, and an allowlist lets out its addresses and the sandbox's own. A sandbox made from the template is held to it from its first boot. One already on it takes the change when it next starts, or now when POST /v1/templates/{id}/apply names it: saving it changes no sandbox that is running. It raises the template's revision, as a change to its secrets does. Sent again with the rule it has, it changes nothing. Only where GET /v1/policy says networkPolicy: elsewhere every template is open, and asking for that is answered with 200.

RequestTypeScript
  1. import { Agental } from "agental-sdk";
  3. const agental = new Agental();
  4. const template = await agental.templates.get("tpl_0123456789abcdef");
  5. await template.setNetwork({
  6. outbound: "allowlist",
  7. allow: ["203.0.113.7"],
  8. });
Answer200 OK · TemplateNetwork
  1. {
  2. "outbound": "open" | "blocked" | "allowlist",
  3. "allow": string[],
  4. }

The template's rule from now on, with each address written one way.

Path

idrequired
string
 e.g. "tpl_0123456789abcdef"

Headers

Authorizationrequired
Bearer key
An API key that may make this call.

Body

outboundrequired
"open" | "blocked" | "allowlist"
open is the internet, which is what a sandbox has when nothing is asked. blocked lets nothing out: names still resolve, and no connection leaves. allowlist lets out only what goes to an address in allow. It is enforced outside the sandbox, on the server it runs on, so nothing running in the sandbox can change it, root included. What reaches the sandbox is not affected: commands, files and its public addresses work as before. Whatever this says, no sandbox reaches another sandbox or a private network, or delivers mail on port 25.
allow
array of string
For allowlist only, and then at least one: IPv4 addresses and ranges, as 203.0.113.7 or 198.51.100.0/24, 100 at most. Names are not taken, and nor is a range inside a private network. A range is kept by its first address, so 198.51.100.7/24 comes back as 198.51.100.0/24. e.g. ["203.0.113.7","198.51.100.0/24"]

Returns

200 The template's rule from now on, with each address written one way.

TemplateNetwork2 fields
outbound
openblockedallowlist
What a sandbox on the template may reach outside itself, before its own addresses.
More open is the internet, which is what a sandbox has when nothing is asked. blocked lets nothing out: names still resolve, and no connection leaves. allowlist lets out only what goes to an address in allow. It is enforced outside the sandbox, on the server it runs on, so nothing running in the sandbox can change it, root included. What reaches the sandbox is not affected: commands, files and its public addresses work as before. Whatever this says, no sandbox reaches another sandbox or a private network, or delivers mail on port 25.
allow
string[]
The IPv4 addresses and ranges an allowlist lets out to, over any protocol and port.
More Empty for open and blocked.

Errors and other answers

400 Invalid request.
400invalid_network_policy what was sent cannot be a rule, and the message says which entry and why.
404 Not found.
409too_many_addresses with the addresses of its own of a sandbox on the template, the rule would come to more than 100 addresses, and the message names the sandbox. Nothing was changed.
501network_policy_unavailable blocked or allowlist was asked for where GET /v1/policy says networkPolicy is false. Nothing was changed.

Every error answers { "error": { "code", "message" } }; a key without the action a call needs answers 403 key_action_forbidden, naming it.

← Get template networkList template sandboxes →