---
title: "Secrets et trafic sortant : des clés qu’une sandbox ne détient jamais | Pethost Agent Sandboxes"
description: "Donnez à une sandbox des clés d’API qu’elle ne détient jamais, insérées par le proxy de sortie pour vos hôtes, et limitez où elle se connecte par une liste."
---

[Documentation Agent Sandboxes](https://pethost.dev/fr/docs/sandboxes/) · Tâches

# Secrets et trafic sortant : des clés qu’une sandbox ne détient jamais

Mis à jour le 22 novembre 2026 · 8 min de lecture

Une sandbox exécute du code auquel vous ne faites pas forcément confiance : celui d’un agent, d’un utilisateur, d’un paquet. Deux paramètres la tiennent dans ses limites. Un secret est une clé que la sandbox ne détient jamais : elle voit un marqueur, et le proxy de sortie met la vraie clé sur le réseau, seulement vers les hôtes que vous nommez. Le trafic sortant, c’est la liste des destinations où elle peut se connecter tout court.

**En bref**

- **`SetSecret`** garde une valeur dans l’espace de travail avec ses hôtes ; une variable qui y est liée (`EnvVar.secret`) contient un marqueur, `phs_…`.
- **La substitution :** dans les en-têtes des requêtes HTTPS vers les seuls hôtes du secret, `Authorization` comme `x-api-key`. Une nouvelle valeur marche aussitôt.
- **`egress.allow` et `deny` :** domaines, sous-domaines, IP et CIDR, avec un port quand ce n’est ni 80 ni 443 ; `deny` l’emporte ; par défaut, partout.
- **Seuls TCP et DNS sortent,** et le DNS de la sandbox ne répond qu’aux noms que la liste autorise.

### Step 1: Enregistrez un secret avec ses hôtes

Un secret a un nom (a-z, 0-9 et « - »), une valeur et les hôtes vers lesquels la valeur peut être envoyée. Définissez-le depuis votre propre environnement, jamais depuis un prompt ou un fichier de la sandbox. Le redéfinir remplace sa valeur et ses hôtes ensemble.

Python

```
import os

sandboxes.set_secret("openai", value=os.environ["OPENAI_API_KEY"], hosts=["api.openai.com"])
```

TypeScript

```
await sandboxes.setSecret({ name: "openai", value: process.env.OPENAI_API_KEY!, hosts: ["api.openai.com"] });
```

Go

```
_, err = client.SetSecret(ctx, &sandboxes.SetSecretRequest{
	Name:  "openai",
	Value: os.Getenv("OPENAI_API_KEY"),
	Hosts: []string{"api.openai.com"},
})
```

Rust

```
sandboxes
    .set_secret(SetSecretRequest {
        name: "openai".into(),
        value: std::env::var("OPENAI_API_KEY")?,
        hosts: vec!["api.openai.com".into()],
        ..Default::default()
    })
    .await?;
```

CLI

```
$ printf %s "$OPENAI_API_KEY" | pethost sandbox secret set openai --host api.openai.com
✓ Set the secret openai for api.openai.com. Bind it:  --env <VARIABLE>=secret:openai
openai
```

### Step 2: Créez une sandbox qui le lie, derrière une liste d’autorisation

Liez une variable au secret dans l’`environment` de la sandbox, et listez dans `egress.allow` où elle peut se connecter : ici l’index des paquets Python et l’hôte du secret. Le trafic sortant doit autoriser les hôtes du secret.

Python

```
from pethost.sandboxes import Egress, Environment, EnvVar, SandboxSettings

sandbox = sandboxes.create_sandbox("base", settings=SandboxSettings(
    environment=Environment(variables=[EnvVar(name="OPENAI_API_KEY", secret="openai")]),
    egress=Egress(allow=["pypi.org", "files.pythonhosted.org", "api.openai.com"]),
))
sandbox_id = sandbox.sandbox_id
```

TypeScript

```
const sandbox = await sandboxes.createSandbox({
  template: "base",
  settings: {
    environment: { variables: [{ name: "OPENAI_API_KEY", secret: "openai" }] },
    egress: { allow: ["pypi.org", "files.pythonhosted.org", "api.openai.com"] },
  },
});
const sandboxId = sandbox.sandboxId;
```

Go

```
sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "base", Settings: &sandboxes.SandboxSettings{
	Environment: &sandboxes.Environment{Variables: []sandboxes.EnvVar{
		{Name: "OPENAI_API_KEY", Source: sandboxes.EnvVarSecret("openai")},
	}},
	Egress: &sandboxes.Egress{Allow: []string{"pypi.org", "files.pythonhosted.org", "api.openai.com"}},
}})
if err != nil {
	log.Fatal(err)
}
id := sandbox.SandboxID
```

Rust

```
let key = EnvVar { name: "OPENAI_API_KEY".into(), source: Some(EnvVarSource::Secret("openai".into())) };
let allow = ["pypi.org", "files.pythonhosted.org", "api.openai.com"].map(String::from).to_vec();
let sandbox = sandboxes
    .create_sandbox(CreateSandboxRequest {
        template: "base".into(),
        settings: Some(SandboxSettings {
            environment: Some(Environment { variables: vec![key] }),
            egress: Some(Egress { allow, ..Default::default() }),
            ..Default::default()
        }),
        ..Default::default()
    })
    .await?;
let id = sandbox.sandbox_id.clone();
```

CLI

```
$ pethost sandbox new --name fenced --env OPENAI_API_KEY=secret:openai \
    --allow pypi.org --allow files.pythonhosted.org --allow api.openai.com
✓ Made sandbox fenced (xhww8xdrh7jj2d8c): default, running, from base@17, in <1 s
xhww8xdrh7jj2d8c
Next:   pethost sandbox run xhww8xdrh7jj2d8c -- <command>   ·   pethost sandbox shell xhww8xdrh7jj2d8c
```

MCP

```
CreateSandbox {"name": "fenced", "settings": {"environment": {"variables": [{"name": "OPENAI_API_KEY", "secret": "openai"}]}, "egress": {"allow": ["pypi.org", "files.pythonhosted.org", "api.openai.com"]}}}
```

### Step 3: Voyez ce que voit la sandbox

À l’intérieur, la variable contient le marqueur, une requête vers l’hôte du secret porte la clé, et un nom que la liste n’autorise pas ne se résout même pas.

Python

```
check = sandboxes.run_command(sandbox_id, command=(
    'echo "$OPENAI_API_KEY" | cut -c1-8; '
    'curl -s -o /dev/null -w "%{http_code}\\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; '
    'curl -sS https://example.com'
))
print(check.stdout, check.stderr)
# phs_szjl
# 401
#  curl: (6) Could not resolve host: example.com
```

TypeScript

```
const check = await sandboxes.runCommand({
  sandboxId,
  command:
    'echo "$OPENAI_API_KEY" | cut -c1-8; ' +
    'curl -s -o /dev/null -w "%{http_code}\\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; ' +
    "curl -sS https://example.com",
});
console.log(check.stdout, check.stderr);
```

Go

```
check, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: id, Command: `echo "$OPENAI_API_KEY" | cut -c1-8; ` +
	`curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; ` +
	`curl -sS https://example.com`})
if err != nil {
	log.Fatal(err)
}
fmt.Println(check.Stdout, check.Stderr)
```

Rust

```
let check = sandboxes
    .run_command(RunCommandRequest {
        sandbox_id: id.clone(),
        command: concat!(
            r#"echo "$OPENAI_API_KEY" | cut -c1-8; "#,
            r#"curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; "#,
            "curl -sS https://example.com",
        )
        .into(),
        ..Default::default()
    })
    .await?;
println!("{} {}", check.stdout, check.stderr);
```

L’exécution ci-dessus avait enregistré une clé inventée, à laquelle OpenAI a répondu 401 ; votre vraie clé reçoit 200. Dans les deux cas, la requête a quitté la sandbox avec la valeur enregistrée à la place du marqueur.

### Step 4: Changez la liste pendant qu’elle tourne

`UpdateSandbox` avec un groupe `egress` remplace toute la liste d’un coup, et ferme les connexions qu’elle n’autorise plus. Une nouvelle valeur de secret n’a besoin de rien : rappelez `SetSecret`, et chaque sandbox qui le lie envoie la nouvelle dès sa prochaine requête.

CLI

```
$ pethost sandbox set fenced --allow pypi.org --allow files.pythonhosted.org --allow api.openai.com --allow github.com:22
```

MCP

```
UpdateSandbox {"sandbox_id": "…", "settings": {"egress": {"allow": ["pypi.org", "files.pythonhosted.org", "api.openai.com", "github.com:22"]}}}
```

## Comment marche un secret

La valeur d’un secret vit dans la console, scellée, et dans la mémoire des serveurs qui font tourner des sandboxes qui le lient : jamais sur le disque d’une sandbox, jamais dans sa mémoire, jamais dans une réponse de l’API. Une variable qui y est liée contient un marqueur qui commence par `phs_`, le même pour chaque processus de la sandbox.

Le proxy de sortie de la sandbox termine le TLS pour les seuls hôtes du secret, avec un certificat de l’autorité propre au serveur, à laquelle la sandbox fait confiance : Node, Python, curl et git sont configurés pour elle. Dans chaque requête vers ces hôtes, il remplace le marqueur par la valeur partout où il apparaît dans la valeur d’un en-tête : `Authorization: Bearer`, `x-api-key`, dans les identifiants de `Authorization: Basic`. Une requête vers tout autre hôte porte le marqueur, qui n’y vaut rien. La substitution se fait dans les en-têtes seulement, pas dans le corps d’une requête.

- **Les hôtes** s’écrivent comme les domaines du trafic sortant : `api.openai.com`, ou `*.example.com` pour ses sous-domaines, avec un port quand ce n’est pas 443.
- **Une nouvelle valeur** marche aussitôt, dans chaque sandbox active et chaque copie qui lie le secret.
- **Un secret lié ne peut pas être supprimé :** `DeleteSecret` est refusé tant qu’une sandbox non supprimée le lie.
- **Un espace de travail contient 100 secrets.** `GetWorkspace` liste leurs noms et leurs hôtes, jamais leurs valeurs.

Les événements de trafic sortant disent, pour chaque hôte et chaque minute, quels secrets ont été substitués dans ses requêtes : [observabilité](https://pethost.dev/fr/docs/sandboxes/observability/).

## Comment marche le trafic sortant

L’`egress` d’une sandbox a deux listes. `allow` dit où elle peut se connecter, `deny` où elle ne le peut pas, et `deny` l’emporte. Par défaut, `allow` vaut `["*"]`, partout. Un groupe envoyé remplace tout le groupe : `deny` envoyé seul laisse `allow` vide ; pour bloquer quelques hôtes, envoyez donc `allow` `["*"]` avec eux. À elles deux, elles contiennent 100 entrées de 255 octets au plus.

| Entrée | Ouvre |
| --- | --- |
| `*` | Partout. |
| `pypi.org` | Ce domaine, sur les ports 80 et 443. |
| `*.github.com` | Ses sous-domaines à toute profondeur, mais pas `github.com` lui-même. |
| `github.com:22` | Ce domaine sur ce port : git sur SSH. |
| `203.0.113.7`, `203.0.113.0/24` | Ces adresses, jointes par adresse, avec `:port` quand ce n’est ni 80 ni 443. |

- **Seuls TCP et DNS sortent d’une sandbox :** pas d’UDP, donc ni QUIC ni HTTP/3, et pas de ping, quoi que dise la liste.
- **Le DNS ne répond qu’aux noms autorisés.** Le résolveur de la sandbox répond REFUSED pour un nom qu’aucune entrée de domaine n’autorise, sans rien demander à personne : aucune donnée ne sort donc par les questions DNS.
- **Le TLS est jugé sur le nom qu’envoie le client,** et le proxy se connecte à l’adresse qu’il a résolue lui-même, jamais à celle qu’a choisie la sandbox. Une entrée de domaine fait confiance à tout ce que servent les adresses de ce nom, y compris les autres sites d’un CDN : une barrière qui doit tenir là nomme des IP, ou lie un secret à l’hôte, dont le proxy lit alors les requêtes une à une.
- **Le HTTP en clair est jugé requête par requête :** une requête vers un autre hôte que celui de sa connexion reçoit 421, et la nouvelle connexion du client est jugée sur cet hôte.
- **SSH et les autres protocoles** ne nomment pas d’hôte, et ne passent que vers une entrée de domaine qui nomme le port, comme `github.com:22`.
- **Toujours refusés :** les adresses privées, link-local et CGNAT, le serveur lui-même, le port 25, et HTTP/2 sans TLS.
- **Un refus** auquel le proxy peut répondre est un 403 qui dit ce qui l’a refusé.

Chaque sandbox a aussi ses propres limites : 200 nouvelles connexions par seconde après une rafale de 1 000, 1 024 ouvertes en même temps, et 200 questions DNS par seconde.

## Des listes qui marchent

| Pour | `allow` |
| --- | --- |
| pip et uv | `pypi.org`, `files.pythonhosted.org` |
| npm | `registry.npmjs.org` |
| git sur HTTPS et SSH | `github.com`, `*.githubusercontent.com`, `github.com:22` |
| Claude Code | `api.anthropic.com` |
| Codex | `api.openai.com` |

Regardez les événements de trafic sortant d’une sandbox pendant une minute de vrai travail pour trouver ce dont elle a encore besoin : chacun dit l’hôte, s’il a été autorisé et combien d’octets sont passés dans chaque sens.

## Quand ça ne marche pas

- **« Could not resolve host » :** aucune entrée n’autorise ce nom. Ajoutez-le à `allow`.
- **Un 403 qui nomme la politique de trafic sortant :** l’hôte, ou son port, n’est pas autorisé, ou une entrée `deny` correspond. SSH a besoin du port dans son entrée.
- **Le service répond 401 avec un secret lié :** la requête est allée vers un hôte que le secret ne nomme pas, ou le client a mis la clé dans le corps, où aucune substitution n’a lieu, ou il épingle ses propres certificats. Nommez l’hôte dans les `hosts` du secret, et envoyez la clé dans un en-tête.
- **`INVALID_ARGUMENT` à une création ou une mise à jour :** les hôtes d’un secret lié ne sont pas autorisés par le trafic sortant de la sandbox, ou le secret n’existe pas. Autorisez-les, ou définissez d’abord le secret.
- **`FAILED_PRECONDITION` sur `DeleteSecret` :** une sandbox le lie. Déliez-le avec `UpdateSandbox`, ou supprimez cette sandbox.
- **`RESOURCE_EXHAUSTED` avec `LimitReached`, `secrets` :** l’espace de travail en a 100. Supprimez-en un que vous ne liez plus.

## Questions

### Un processus de la sandbox peut-il lire ma clé d’API ?

Non. Une variable liée contient un marqueur ; le proxy de sortie, hors de la VM, met la clé dans les requêtes vers les hôtes du secret.

### Quelles requêtes reçoivent la vraie clé ?

Les requêtes HTTPS vers les hôtes que nomme le secret, dans leurs en-têtes. Tout autre hôte reçoit le marqueur.

### Comment couper l’accès à Internet dans une sandbox ?

Envoyez `egress` avec un `allow` vide : rien ne sort, et le DNS ne résout rien. N’ajoutez que ce dont le travail a besoin.

### Une sandbox a-t-elle de l’UDP ?

Non. Seuls TCP et DNS sortent d’une sandbox : QUIC, HTTP/3 et ping ne marchent donc pas, quoi que dise la liste.

### Les changements de trafic sortant s’appliquent-ils à une sandbox active ?

Oui, aussitôt : les connexions que la nouvelle liste n’autorise plus sont fermées.

[PrécédentTemplates : des sandboxes prêtes à travailler dès le démarrage](https://pethost.dev/fr/docs/sandboxes/templates/) [SuivantDupliquer une sandbox (fork), mémoire et processus compris](https://pethost.dev/fr/docs/sandboxes/forks/)

## Essayez Pethost Agent Sandboxes

Un essai gratuit de 7 jours avec 1 $ de consommation et 4 vCPU, avec une carte. Ensuite, une offre dès 20 $ par mois, qui inclut autant de consommation.

[Démarrer l’essai gratuit](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Templates](https://pethost.dev/fr/templates/)
- [À propos](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/fr/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Conditions](https://pethost.dev/terms/)
- [Confidentialité](https://pethost.dev/privacy/)
- [Remboursements](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bases de données

- [Postgres](https://pethost.dev/fr/postgres/)
- [Valkey](https://pethost.dev/fr/valkey/)

Agent Sandboxes

- [Sandboxes](https://pethost.dev/fr/sandboxes/)
- [Tarifs](https://pethost.dev/fr/sandboxes/#pricing)
- [Docs](https://pethost.dev/fr/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Comparatifs

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/fr/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/fr/blog/coolify-cloud-vs-dokploy-cloud/)
- [Tarifs Railway vs Render vs Fly.io](https://pethost.dev/fr/blog/railway-vs-render-vs-fly-io-pricing/)
- [Hébergement Docker Compose managé](https://pethost.dev/fr/blog/managed-docker-compose-hosting/)

Alternatives

- [Alternatives à Railway](https://pethost.dev/fr/blog/railway-alternatives/)
- [Alternatives à Heroku](https://pethost.dev/fr/blog/heroku-alternatives/)
- [Alternatives à Dokploy](https://pethost.dev/fr/blog/dokploy-alternatives/)
- [Alternatives à Coolify](https://pethost.dev/fr/blog/coolify-alternatives/)
- [Alternatives à Render](https://pethost.dev/fr/blog/render-alternatives/)
- [Alternatives à Sliplane](https://pethost.dev/fr/blog/sliplane-alternatives/)
