# Secrets and network access

Deployed tools run without internet access and without your `.env`. To call an
external API from a deployed tool, turn on egress and give the project the
credentials it needs as secrets.

## Turn on network access

In `zenitya.json`:

```json
{
  "configVersion": 1,
  "name": "orders",
  "entrypoint": "src/index.ts",
  "network": { "allowEgress": true }
}
```

Then `zya deploy`. The setting takes effect when that deployment becomes
active. With egress on, tools can reach any host by name. Raw IP addresses,
private ranges and local addresses are always refused. Without `network`, or
with `allowEgress: false`, tools cannot open connections at all.

## Set secrets

```sh
zya secrets set API_TOKEN --stdin < token.txt
printf %s "$STRIPE_KEY" | zya secrets set STRIPE_KEY --stdin
zya secrets set REGION eu-west-1
zya secrets list
zya secrets delete REGION
```

Managing secrets needs an owner or admin login, or a machine key with the
`configure` scope.

- Names are upper-case letters, digits and underscores, starting with a letter,
  at most 64 characters: `API_TOKEN`, `STRIPE_KEY`. Names such as `PATH` and
  `HOME`, and the prefixes `ZENITYA_`, `ZYA_` and `CF_`, are reserved.
- Values are kept exactly as given, 1 to 16 KiB of UTF-8. There is no type
  conversion; parse JSON yourself if you store it.
- Prefer `--stdin`. A value typed on the command line can end up in shell
  history, process listings and CI logs.
- Values are encrypted at rest and never shown again: `secrets list` prints
  names and when each changed.

## Read them in a tool

Every secret of the project is an environment variable in every deployed tool:

```ts
execute: async ({ query }, { signal }) => {
  const response = await fetch(`https://api.example.com/search?q=${encodeURIComponent(query)}`, {
    headers: { Authorization: `Bearer ${process.env.API_TOKEN}` },
    signal,
  });
  if (!response.ok) throw new Error(`Search failed with HTTP ${response.status}.`);
  return await response.json();
},
```

A secret change applies to the next call; you do not need to deploy again.

## Locally

`zya exec --local` never receives project secrets. Put the same names in a
`.env` file in the project directory for local runs. `.env` is never uploaded.

## What to keep in mind

Every secret is available to all of the project's code, including its
dependencies, and code with egress can send it anywhere. Keep projects that
need different credentials separate, review dependencies, and never log
secrets or return them in a tool's output.