Skip to main content
Not yet released. This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.

​
Goal

Decide which addresses an agent may reach, give it the keys it needs, and keep other keys out of its hands.

​
Prerequisites

  • An agent that needs to reach a service outside StackShift.
  • For a key sent on the way out, the service’s address already on the agent’s internet list.

​
Workflow

1
List the addresses the agent needs under internet: in stackshift.yaml, or in the agent’s settings under “Also these addresses”.
2
Save the agent’s own keys for those services as secrets: in settings, or with stackshift agents secrets set. They are shown once and never again.
3
For a service whose key the agent should never hold, open settings and choose “Add a key sent on the way out”. Pick the address, the header name (Authorization by default) and the key.
4
In the agent’s code, call agent.fetch(url) for those addresses.
5
Check the agent’s settings: they show how many requests to other addresses were blocked this week.

​
Three internet settings

Private and internal networks stay blocked whatever you choose. The agent’s settings show how many requests to other addresses were blocked this week.
  • Default: only StackShift, model access and the delivery of events to the agent.
  • Also these addresses: the hosts you list. Agents may block on their own; allowing new addresses asks the owner.
  • Anywhere: all outside access. It always asks the owner.

​
The agent’s own secrets

A secret is a key the agent uses for another service, such as a shop’s API key. It is encrypted and delivered only to this agent, and it appears in the agent’s environment under the name you gave it (capital letters, digits and underscores). Provider model keys are never secrets the agent holds.

​
Keys sent on the way out

For an address on the internet list, you can save a header, such as Authorization: Bearer …, that StackShift adds to the agent’s requests to that address. The agent never holds the key. If its code is wrong or leaked, the key is not in it. agent.fetch(url, init) does this for you: it sends requests for those addresses through StackShift and everything else directly. Only HTTPS requests to the standard port go this way. Set the key by API with PUT /api/v1/agents/{id}/egress-keys/{host} and {"header": "Authorization", "value": "…"}; remove it with DELETE. Without the SDK, the agent finds the key’s placeholder in the environment variable STACKSHIFT_EGRESS_KEY_<HOST>, with the address in capitals and every other character an underscore. Send the request to $STACKSHIFT_SECRET_PROXY_URL/<key-id>/<host>/<path> with the placeholder in the X-Stackshift-Secret header; <key-id> is the id inside the placeholder.

​
Expected result

The agent reaches only the addresses you allowed. Keys it needs reach its code as secrets. Keys sent on the way out are added by StackShift, so they are not in the agent at all.

​
Common failures

  • The request fails or times out: the address is not on the internet list. Add it and deploy, or change the setting.
  • Allowing an address that was not allowed before, or choosing “Anywhere”, waits for the owner to approve. An agent may block addresses on its own, not allow them.
  • Adding a key sent on the way out says the address is not listed: add the address to the internet list first.
  • A wildcard such as *.example.com is refused. List each address.

The agent block in stackshift.yaml

Reference for the type: agent service: what wakes the agent, how it pays, what it may reach and which actions it has.

Budgets, stopping and runaway protection

Three budgets, a Stop button that halts everything at once, and layers that stop an agent that loops or fails.