---
title: "Lancer des commandes et modifier des fichiers dans une sandbox | Pethost Agent Sandboxes"
description: "Lancez des commandes shell dans une sandbox et attendez leur sortie ou leur port, suivez les longues, modifiez des fichiers et déplacez les gros par des liens."
---

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

# Lancer des commandes et modifier des fichiers dans une sandbox

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

Lancez une commande dans une sandbox et obtenez sa sortie et son code de sortie en un appel, suivez une longue commande pendant qu’elle tourne, modifiez des fichiers par remplacement exact, déplacez des fichiers de toute taille par des liens, et ouvrez un terminal dans un navigateur.

**En bref**

- **`RunCommand`** lance `bash -lc` en tant que `user` dans `/home/user` et attend jusqu’à 45 s : son code de sortie et les derniers 32 KiB de sa sortie, ou RUNNING avec son ID.
- **`WatchCommand`** diffuse la sortie d’une commande au fil de l’eau ; `GetCommand` attend de nouveau et ne lit que ce qui est nouveau.
- **`WriteFiles`** écrit, modifie, déplace et supprime des fichiers en un appel, dans l’ordre ; une modification remplace un texte présent exactement une fois.
- **Des liens** déplacent des fichiers de toute taille et ouvrent un terminal dans un navigateur.

Les exemples reprennent le [démarrage rapide](https://pethost.dev/fr/docs/sandboxes/quickstart/) : `sandboxes` (`client` en Go) est un client, et l’ID de la sandbox est sous la main.

### Step 1: Lancez une commande

Une commande est une seule chaîne, exécutée par `bash -lc` : les pipes, `&&` et les variables marchent donc. `cwd` et `user` changent où et sous quelle identité elle s’exécute ; `user` vaut `root` ou la valeur par défaut, `user`, qui a sudo sans mot de passe.

Python

```
command = sandboxes.run_command(sandbox_id, command="uname -r && whoami", cwd="/tmp")
print(command.exit_code)
print(command.stdout)
# 0
# 6.18.63
# user
```

TypeScript

```
const command = await sandboxes.runCommand({ sandboxId, command: "uname -r && whoami", cwd: "/tmp" });
console.log(command.exitCode);
console.log(command.stdout);
```

Go

```
command, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: id, Command: "uname -r && whoami", Cwd: "/tmp"})
if err != nil {
	log.Fatal(err)
}
fmt.Println(*command.ExitCode)
fmt.Println(command.Stdout)
```

Rust

```
let command = sandboxes
    .run_command(RunCommandRequest {
        sandbox_id: id.clone(),
        command: "uname -r && whoami".into(),
        cwd: "/tmp".into(),
        ..Default::default()
    })
    .await?;
println!("{:?}", command.exit_code);
println!("{}", command.stdout);
```

CLI

```
$ pethost sandbox run api-dev --cwd /tmp -- 'uname -r && whoami'
6.18.63
user
```

### Step 2: Suivez une longue commande

Avec `wait_seconds` à 0, l’appel répond dès que la commande a démarré. `WatchCommand` envoie ensuite sa sortie à partir des derniers 64 KiB, au fil de l’eau, puis la commande telle qu’elle s’est terminée.

Python

```
import sys

job = sandboxes.run_command(
    sandbox_id,
    command="for i in 1 2 3; do echo step $i; sleep 20; done",
    wait_seconds=0,
    timeout_seconds=600,
)
for out in sandboxes.watch_command(sandbox_id, command_id=job.command_id):
    if out.stdout is not None:
        sys.stdout.write(out.stdout.decode())
    if out.ended is not None:
        print("exit", out.ended.exit_code)
# step 1
# step 2
# step 3
# exit 0
```

TypeScript

```
const job = await sandboxes.runCommand({
  sandboxId,
  command: "for i in 1 2 3; do echo step $i; sleep 20; done",
  waitSeconds: 0,
  timeoutSeconds: 600,
});
for await (const out of sandboxes.watchCommand({ sandboxId, commandId: job.commandId })) {
  if (out.output === "stdout") process.stdout.write(out.stdout);
  if (out.output === "ended") console.log("exit", out.ended.exitCode);
}
```

Go

```
job, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{
	SandboxID:      id,
	Command:        "for i in 1 2 3; do echo step $i; sleep 20; done",
	WaitSeconds:    new(uint32(0)),
	TimeoutSeconds: 600,
})
if err != nil {
	log.Fatal(err)
}
for out, err := range client.WatchCommand(ctx, &sandboxes.WatchCommandRequest{SandboxID: id, CommandID: job.CommandID}) {
	if err != nil {
		log.Fatal(err)
	}
	switch output := out.Output.(type) {
	case sandboxes.CommandOutputStdout:
		os.Stdout.Write(output)
	case sandboxes.CommandOutputEnded:
		fmt.Println("exit", *output.ExitCode)
	}
}
```

Rust

```
let job = sandboxes
    .run_command(RunCommandRequest {
        sandbox_id: id.clone(),
        command: "for i in 1 2 3; do echo step $i; sleep 20; done".into(),
        wait_seconds: Some(0),
        timeout_seconds: 600,
        ..Default::default()
    })
    .await?;
let mut output = sandboxes.watch_command(WatchCommandRequest {
    sandbox_id: id.clone(),
    command_id: job.command_id,
});
while let Some(out) = output.next().await {
    match out?.output {
        Some(CommandOutputOutput::Stdout(bytes)) => print!("{}", String::from_utf8_lossy(&bytes)),
        Some(CommandOutputOutput::Ended(ended)) => println!("exit {:?}", ended.exit_code),
        _ => {}
    }
}
```

CLI

```
$ pethost sandbox run api-dev --timeout 10m -- 'for i in 1 2 3; do echo step $i; sleep 20; done'
step 1
step 2
step 3
```

Sans flux, `GetCommand` attend de nouveau jusqu’à 45 s. Passez le `stdout_bytes` de la dernière réponse lue comme `stdout_after_bytes`, et il n’envoie que ce qui est venu après.

### Step 3: Écrivez, modifiez et lisez des fichiers

`WriteFiles` prend une liste de changements et les applique dans l’ordre : `text` ou `data` écrit un fichier entier (avec `mode`, sinon `0644`), `edit` remplace un morceau exact d’un fichier, `move_to` le déplace, `delete` supprime un fichier ou un dossier, `make_directory` en crée un. Les dossiers manquants sont créés, et le lot s’arrête au premier changement qui échoue.

Python

```
from pethost.sandboxes import FileChange, TextEdit

done = sandboxes.write_files(sandbox_id, changes=[
    FileChange(path="app/run.sh", text="#!/bin/sh\necho ready\n", mode="0755"),
    FileChange(path="app/run.sh", edit=TextEdit(old_text="ready", new_text="ready to go")),
])
print(done.done_count, done.failure.name)
for entry in sandboxes.list_files(sandbox_id, path="app").files:
    print(entry.path, entry.mode, entry.size_bytes)
print(sandboxes.read_file(sandbox_id, path="app/run.sh").text)
# 2 UNSPECIFIED
# /home/user/app/run.sh 0755 27
# #!/bin/sh
# echo ready to go
```

TypeScript

```
const done = await sandboxes.writeFiles({
  sandboxId,
  changes: [
    { path: "app/run.sh", text: "#!/bin/sh\necho ready\n", mode: "0755" },
    { path: "app/run.sh", edit: { oldText: "ready", newText: "ready to go" } },
  ],
});
console.log(done.doneCount, done.failure);
const { files } = await sandboxes.listFiles({ sandboxId, path: "app" });
for (const entry of files) console.log(entry.path, entry.mode, entry.sizeBytes);
console.log((await sandboxes.readFile({ sandboxId, path: "app/run.sh" })).text);
```

Go

```
done, err := client.WriteFiles(ctx, &sandboxes.WriteFilesRequest{SandboxID: id, Changes: []sandboxes.FileChange{
	{Path: "app/run.sh", Change: sandboxes.FileChangeText("#!/bin/sh\necho ready\n"), Mode: "0755"},
	{Path: "app/run.sh", Change: sandboxes.FileChangeEdit{OldText: "ready", NewText: "ready to go"}},
}})
if err != nil {
	log.Fatal(err)
}
fmt.Println(done.DoneCount, done.Failure)
list, err := client.ListFiles(ctx, &sandboxes.ListFilesRequest{SandboxID: id, Path: "app"})
if err != nil {
	log.Fatal(err)
}
for _, entry := range list.Files {
	fmt.Println(entry.Path, entry.Mode, entry.SizeBytes)
}
```

Rust

```
let script = |change| FileChange { path: "app/run.sh".into(), change: Some(change), ..Default::default() };
let done = sandboxes
    .write_files(WriteFilesRequest {
        sandbox_id: id.clone(),
        changes: vec![
            FileChange { mode: "0755".into(), ..script(FileChangeChange::Text("#!/bin/sh\necho ready\n".into())) },
            script(FileChangeChange::Edit(TextEdit { old_text: "ready".into(), new_text: "ready to go".into() })),
        ],
    })
    .await?;
println!("{} {:?}", done.done_count, done.failure);
let list = sandboxes
    .list_files(ListFilesRequest { sandbox_id: id.clone(), path: "app".into(), ..Default::default() })
    .await?;
for entry in list.files {
    println!("{} {} {}", entry.path, entry.mode, entry.size_bytes);
}
```

### Step 4: Déplacez un gros fichier par un lien

Un appel transporte 1 MiB, `WriteFiles` 17 MiB et `ReadFile` 1 MiB. Un fichier de toute taille passe plutôt par un lien : `CreateLink` avec `download_path` donne une URL à lire en GET, un dossier arrivant en .tar ; avec `upload_path`, une URL où envoyer les octets du fichier en PUT. Chacune marche une fois, et va directement au serveur de la sandbox.

Python

```
upload = sandboxes.create_link(sandbox_id, upload_path="data/train.csv")
results = sandboxes.create_link(sandbox_id, download_path="results")
print(upload.url)
print(results.url)
# https://link-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network/sbl.eyJzIjoiZTlicHJidzFob3ZqNnN3NSIs…
# https://link-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network/sbl.eyJzIjoiZTlicHJidzFob3ZqNnN3NSIs…
```

TypeScript

```
const upload = await sandboxes.createLink({ sandboxId, uploadPath: "data/train.csv" });
const results = await sandboxes.createLink({ sandboxId, downloadPath: "results" });
console.log(upload.url);
console.log(results.url);
```

Go

```
upload, err := client.CreateLink(ctx, &sandboxes.CreateLinkRequest{SandboxID: id, Target: sandboxes.CreateLinkUploadPath("data/train.csv")})
if err != nil {
	log.Fatal(err)
}
results, err := client.CreateLink(ctx, &sandboxes.CreateLinkRequest{SandboxID: id, Target: sandboxes.CreateLinkDownloadPath("results")})
if err != nil {
	log.Fatal(err)
}
fmt.Println(upload.URL)
fmt.Println(results.URL)
```

Rust

```
let link = |target| CreateLinkRequest { sandbox_id: id.clone(), target: Some(target), ..Default::default() };
let upload = sandboxes.create_link(link(CreateLinkRequestTarget::UploadPath("data/train.csv".into()))).await?;
let results = sandboxes.create_link(link(CreateLinkRequestTarget::DownloadPath("results".into()))).await?;
println!("{}", upload.url);
println!("{}", results.url);
```

CLI

```
$ pethost sandbox cp ./data/train.csv api-dev:data/train.csv
✓ Copied ./data/train.csv to zt01ocz93yiwpy31:data/train.csv · 22 KB in <1 s
$ pethost sandbox cp api-dev:results ./results
✓ Copied zt01ocz93yiwpy31:results to ./results · 4 KB in <1 s
```

```
curl -T train.csv "$UPLOAD_URL"
curl -o results.tar "$RESULTS_URL"
```

### Step 5: Ouvrez un terminal dans un navigateur

`CreateLink` avec `terminal` donne une page avec un shell dans la sandbox, où une personne peut taper ; son `command` lance un programme à la place du shell, comme `claude`. Une WebSocket vers la même URL transporte les octets du terminal dans les deux sens, pour un terminal à vous.

Python

```
from pethost.sandboxes import TerminalLink

print(sandboxes.create_link(sandbox_id, terminal=TerminalLink(), ttl_seconds=900).url)
# https://link-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network/sbl.eyJzIjoiZTlicHJidzFob3ZqNnN3NSIs…
```

TypeScript

```
const terminal = await sandboxes.createLink({ sandboxId, terminal: {}, ttlSeconds: 900 });
console.log(terminal.url);
```

Go

```
terminal, err := client.CreateLink(ctx, &sandboxes.CreateLinkRequest{
	SandboxID:  id,
	Target:     sandboxes.CreateLinkTerminal{},
	TTLSeconds: 900,
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(terminal.URL)
```

Rust

```
let terminal = sandboxes
    .create_link(CreateLinkRequest {
        sandbox_id: id.clone(),
        target: Some(CreateLinkRequestTarget::Terminal(TerminalLink::default())),
        ttl_seconds: 900,
    })
    .await?;
println!("{}", terminal.url);
```

CLI

```
$ pethost sandbox open api-dev --terminal
✓ Opened the terminal of e9bprbw1hovj6sw5 in your browser.
$ pethost sandbox shell api-dev
To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.

user@e9bprbw1hovj6sw5:~$
```

Un lien expire au bout d’une heure, sauf si `ttl_seconds` dit autre chose, 86 400 s au plus, et porte un token dans son URL : donnez-le à la personne qui s’en servira, jamais à une page que d’autres lisent. En créer un ne réveille rien.

## Où s’exécute une commande

Une commande s’exécute dans la VM de la sandbox en tant que `user` (uid 1000, sudo sans mot de passe, dans le groupe `docker`) dans `/home/user`, ou en tant que `root`. Son environnement est celui du template, avec par-dessus les variables propres à la sandbox (`settings.environment`). `stdin` lui donne une entrée, qui se ferme ensuite. Une commande tourne jusqu’à ce qu’elle se termine, jusqu’à `timeout_seconds`, ou jusqu’à `StopCommand` : c’est l’attente de l’appel qui prend fin, pas la commande.

Un appel vers une sandbox en pause la réveille d’abord, en 80 ms environ. Un processus laissé en arrière-plan (un serveur lancé avec `&`) survit aux pauses, mais ne garde pas à lui seul la sandbox éveillée : lancez une longue tâche avec `keep_awake`, pour que le délai de pause l’attende ([keep_awake](https://pethost.dev/fr/docs/sandboxes/lifecycle/#keep-awake)).

## Sortie, positions et historique

Une réponse contient les derniers 32 KiB de stdout et de stderr, en UTF-8, avec `output_truncated` quand le début a été coupé, et `stdout_bytes` et `stderr_bytes`, tout ce qui a été écrit. `exit_code` est celui du shell : 128 plus le numéro du signal quand un signal l’a terminée, et absent tant qu’elle tourne. La sandbox garde ses 100 dernières commandes terminées pour `GetCommand`. `ListCommands` liste celles qui tournent maintenant, lancées par l’API, par SSH ou dans un terminal.

`StopCommand` envoie SIGTERM, puis SIGKILL 10 s plus tard si la commande tourne encore. Appelé pour une commande terminée, il tue ce qu’elle a laissé tourner en arrière-plan.

## Modifications par remplacement exact

Une `edit` remplace `old_text` par `new_text` là où `old_text` apparaît exactement une fois dans le fichier, de 16 MiB au plus. Absent, c’est `EDIT_NOT_FOUND` ; présent deux fois ou plus, `EDIT_AMBIGUOUS`, et le fichier reste inchangé dans les deux cas. C’est la modification que font les agents de code, et elle échoue franchement là où un numéro de ligne aurait été périmé. Une écriture remplace un fichier entier et garde son propriétaire et son mode ; elle écrit à travers un lien symbolique, vers sa cible.

`WatchFiles` diffuse ce qui est créé, écrit, supprimé et renommé dans un dossier, avec `recursive` pour ce qui est en dessous. `OVERFLOW` dit que des événements ont été perdus : listez de nouveau le dossier.

## Docker dans une sandbox

Chaque sandbox issue de `base` a Docker, avec Compose et Buildx. Son démon démarre à la première connexion à `/var/run/docker.sock` et ne coûte rien jusque-là. Les images et les conteneurs sont sur le disque de la sandbox : un arrêt les garde donc, et un template les emporte. Les téléchargements depuis Docker Hub passent d’abord par un miroir.

## Quand ça ne marche pas

- **La réponse est RUNNING, sans code de sortie :** la commande a duré plus que `wait_seconds` et continue. Suivez-la avec `WatchCommand`, ou attendez avec `GetCommand`.
- **La sandbox s’est mise en pause pendant un long build :** rien ne l’appelait pendant le build. Lancez ce genre de travail avec `keep_awake` et un `timeout_seconds`.
- **`failure` vaut `EDIT_NOT_FOUND` ou `EDIT_AMBIGUOUS` :** relisez le fichier et envoyez un `old_text` présent une seule fois ; les changements qui le précèdent dans le lot ont été faits (`done_count`).
- **`RESOURCE_EXHAUSTED` sans `LimitReached` :** la requête dépassait sa limite (un fichier de plus de 17 MiB : utilisez un lien d’envoi), ou la sandbox sert déjà 64 appels en même temps. Terminez-en un, ou attendez.
- **`FAILED_PRECONDITION` avec `Stopped` :** la sandbox est arrêtée. `ResumeSandbox` la démarre, ses fichiers tels qu’elle les a laissés.
- **Une commande qui était RUNNING est `LOST` :** la sandbox a perdu sa mémoire (elle s’est arrêtée) pendant que la commande tournait. Relancez-la.

## Questions

### Combien de temps une commande peut-elle tourner ?

Aussi longtemps qu’il le faut : l’appel attend jusqu’à 45 s et la commande continue. Seuls `timeout_seconds` ou `StopCommand` la terminent plus tôt.

### Puis-je lancer des commandes en root ?

Oui : `user` à `root`, ou `sudo`, que `user` a sans mot de passe.

### Comment envoyer un gros fichier dans une sandbox ?

`CreateLink` avec `upload_path` donne une URL où envoyer le fichier en PUT, de toute taille, ou `pethost sandbox cp` le fait pour vous.

### Puis-je faire tourner Docker dans une sandbox ?

Oui. Docker, Compose et Buildx sont dans `base`, et le démon démarre à la première utilisation.

### Un processus en arrière-plan garde-t-il la sandbox éveillée ?

Non. Il survit aux pauses, et une requête vers son port réveille la sandbox, mais seuls les appels, les sessions et les commandes `keep_awake` l’empêchent de se mettre en pause.

[PrécédentBonnes pratiques pour Pethost Agent Sandboxes](https://pethost.dev/fr/docs/sandboxes/best-practices/) [SuivantPorts et prévisualisations : les URL d’une sandbox](https://pethost.dev/fr/docs/sandboxes/ports-and-previews/)

## 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/)
