> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Internet access and secrets for agents

> An agent reaches only StackShift and model access until you allow more. Its keys for other services stay secret, and some it never holds at all.

> [!NOTE]
>
> **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

**Step 1**

List the addresses the agent needs under `internet:` in `stackshift.yaml`, or in the agent’s settings under “Also these addresses”.

**Step 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.

**Step 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.

**Step 4**

In the agent’s code, call `agent.fetch(url)` for those addresses.

**Step 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.

```bash theme={null}
printf %s "$SHOP_API_KEY" | stackshift agents secrets set supplies-agent SHOP_API_KEY
stackshift agents secrets unset supplies-agent SHOP_API_KEY
```

## 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.

```ts TypeScript theme={null}
const response = await agent.fetch('https://api.millsco.com/orders/A-1043')
const order = await response.json()
```

```python Python theme={null}
response = await agent.fetch("https://api.millsco.com/orders/A-1043")
order = response.json()
```

## Expected result

> [!TIP]
>
> 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

> [!WARNING]
>
> * 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.

## Related guides

> [card] [The agent block in stackshift.yaml](https://docs.stackshift.cloud/ai-features/hosted-agents-manifest.md)
>
> Reference for the `type: agent` service: what wakes the agent, how it pays, what it may reach and which actions it has.

> [card] [Budgets, stopping and runaway protection](https://docs.stackshift.cloud/ai-features/hosted-agents-budgets.md)
>
> Three budgets, a Stop button that halts everything at once, and layers that stop an agent that loops or fails.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.