---
title: "Ejecuta comandos y edita archivos en un sandbox | Pethost Agent Sandboxes"
description: "Ejecuta comandos en un sandbox y espera su salida o su puerto, transmite los largos, edita archivos por reemplazo exacto y mueve archivos grandes con enlaces."
---

[Documentación de Agent Sandboxes](https://pethost.dev/es/docs/sandboxes/) · Tareas

# Ejecuta comandos y edita archivos en un sandbox

Actualizado 22 de noviembre de 2026 · 9 min de lectura

Ejecuta un comando en un sandbox y recibe su salida y su código de salida en una llamada, sigue uno largo mientras se ejecuta, edita archivos por reemplazo exacto, mueve archivos de cualquier tamaño a través de enlaces y abre una terminal en un navegador.

**En resumen**

- **`RunCommand`** ejecuta `bash -lc` como `user` en `/home/user` y espera hasta 45 s: su código de salida y los últimos 32 KiB de su salida, o RUNNING con su id.
- **`WatchCommand`** transmite la salida de un comando a medida que llega; `GetCommand` vuelve a esperar y solo lee lo nuevo.
- **`WriteFiles`** escribe, edita, mueve y elimina archivos en una llamada, en orden; una edición reemplaza un texto que aparece exactamente una vez.
- **Los enlaces** mueven archivos de cualquier tamaño y abren una terminal en un navegador.

Los ejemplos siguen desde la [guía rápida](https://pethost.dev/es/docs/sandboxes/quickstart/): `sandboxes` (`client` en Go) es un cliente, y tienes a mano el id del sandbox.

### Step 1: Ejecuta un comando

Un comando es un string que ejecuta `bash -lc`, así que funcionan las tuberías, `&&` y las variables. `cwd` y `user` cambian dónde y como quién se ejecuta; `user` es `root` o el valor por defecto, `user`, que tiene sudo sin contraseña.

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: Sigue un comando largo

Con `wait_seconds` a 0, la llamada responde en cuanto se inicia el comando. `WatchCommand` envía entonces su salida desde los últimos 64 KiB en adelante, a medida que llega, y el comando tal como terminó al final.

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
```

Sin stream, `GetCommand` vuelve a esperar hasta 45 s. Pasa el `stdout_bytes` de la última respuesta que leíste como `stdout_after_bytes`, y solo enviará lo que llegó después.

### Step 3: Escribe, edita y lee archivos

`WriteFiles` toma una lista de cambios y los hace en orden: `text` o `data` escribe un archivo entero (con `mode`, si no `0644`), `edit` reemplaza un fragmento exacto de un archivo, `move_to` lo mueve, `delete` elimina un archivo o un directorio, `make_directory` crea uno. Los directorios que faltan se crean, y el lote se detiene en el primer cambio que falla.

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: Mueve un archivo grande a través de un enlace

Una llamada lleva 1 MiB, `WriteFiles` 17 MiB y `ReadFile` 1 MiB. Un archivo de cualquier tamaño se mueve mejor a través de un enlace: `CreateLink` con `download_path` da una URL para hacer GET, y un directorio llega como .tar; con `upload_path`, una URL a la que hacer PUT de los bytes del archivo. Cada una funciona una vez, y va directa al servidor del 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: Abre una terminal en un navegador

`CreateLink` con `terminal` da una página con una shell en el sandbox, para que una persona escriba en ella; su `command` ejecuta un programa en lugar de la shell, como `claude`. Un WebSocket a la misma URL lleva los bytes de la terminal en los dos sentidos, para una terminal propia.

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 enlace caduca tras una hora salvo que `ttl_seconds` diga otra cosa, 86.400 s como máximo, y lleva un token en su URL: dáselo a la persona que lo usará, nunca a una página que lean otros. Crear uno no despierta nada.

## Dónde se ejecuta un comando

Un comando se ejecuta en la VM del sandbox como `user` (uid 1000, sudo sin contraseña, en el grupo `docker`) en `/home/user`, o como `root`. Su entorno es el de la plantilla, con las variables propias del sandbox por encima (`settings.environment`). `stdin` le da una entrada, que después se cierra. Un comando se ejecuta hasta que termina, hasta `timeout_seconds` o hasta `StopCommand`: lo que termina es la espera de la llamada, no el comando.

Una llamada a un sandbox en pausa lo despierta primero, en unos 80 ms. Un proceso que queda en segundo plano (un servidor iniciado con `&`) sobrevive a las pausas, pero no mantiene despierto el sandbox por sí solo: inicia un trabajo largo con `keep_awake`, para que el temporizador de pausa lo espere ([keep_awake](https://pethost.dev/es/docs/sandboxes/lifecycle/#keep-awake)).

## Salida, offsets e historial

Una respuesta trae los últimos 32 KiB de stdout y de stderr, en UTF-8, con `output_truncated` cuando se cortó el principio, y `stdout_bytes` y `stderr_bytes`, todo lo que se escribió. `exit_code` es el de la shell: 128 más el número de la señal cuando lo terminó una señal, y no aparece mientras se ejecuta. El sandbox guarda sus últimos 100 comandos terminados para `GetCommand`. `ListCommands` lista los que se ejecutan ahora, iniciados por la API, por SSH o en una terminal.

`StopCommand` envía SIGTERM, y SIGKILL 10 s después si el comando sigue en ejecución. Si se llama para un comando que ya terminó, mata lo que ese comando dejó ejecutándose en segundo plano.

## Ediciones por reemplazo exacto

Un `edit` reemplaza `old_text` por `new_text` donde `old_text` aparece exactamente una vez en el archivo, de 16 MiB como máximo. Si no está, es `EDIT_NOT_FOUND`; si está dos veces o más, `EDIT_AMBIGUOUS`, y en los dos casos el archivo no cambia. Es la edición que hacen los agentes de programación, y falla de forma visible donde un número de línea se habría quedado desfasado. Una escritura reemplaza un archivo entero y conserva su propietario y su modo; escribe a través de un enlace simbólico en su destino.

`WatchFiles` transmite lo que se crea, se escribe, se elimina y se renombra en un directorio, con `recursive` para lo que hay por debajo. `OVERFLOW` dice que se perdieron eventos: vuelve a listar el directorio.

## Docker en un sandbox

Todos los sandboxes desde `base` tienen Docker, con Compose y Buildx. Su daemon se inicia con la primera conexión a `/var/run/docker.sock` y no cuesta nada hasta entonces. Las imágenes y los contenedores están en el disco del sandbox, así que una detención los conserva y una plantilla los lleva. Las descargas desde Docker Hub pasan primero por un mirror.

## Cuando no funciona

- **La respuesta es RUNNING, sin código de salida:** el comando tardó más que `wait_seconds` y sigue en ejecución. Síguelo con `WatchCommand`, o espera con `GetCommand`.
- **El sandbox se pausó a mitad de un build largo:** nada lo llamó mientras se ejecutaba el build. Inicia ese trabajo con `keep_awake` y un `timeout_seconds`.
- **`failure` es `EDIT_NOT_FOUND` o `EDIT_AMBIGUOUS`:** vuelve a leer el archivo y envía un `old_text` que aparezca una vez; los cambios anteriores del lote sí se hicieron (`done_count`).
- **`RESOURCE_EXHAUSTED` sin `LimitReached`:** la petición pasó de su límite (un archivo de más de 17 MiB: usa un enlace de subida), o el sandbox ya atiende 64 llamadas a la vez. Termina una, o espera.
- **`FAILED_PRECONDITION` con `Stopped`:** el sandbox está detenido. `ResumeSandbox` lo inicia, con sus archivos como los dejó.
- **Un comando que estaba RUNNING pasa a `LOST`:** el sandbox perdió su memoria (se detuvo) mientras el comando se ejecutaba. Ejecútalo otra vez.

## Preguntas

### ¿Cuánto tiempo puede ejecutarse un comando?

El que necesite: la llamada espera hasta 45 s y el comando sigue. Solo `timeout_seconds` o `StopCommand` lo terminan antes.

### ¿Puedo ejecutar comandos como root?

Sí: `user` `root`, o `sudo`, que `user` tiene sin contraseña.

### ¿Cómo subo un archivo grande a un sandbox?

`CreateLink` con `upload_path` da una URL a la que hacer PUT del archivo, de cualquier tamaño, o `pethost sandbox cp` lo hace por ti.

### ¿Puedo ejecutar Docker dentro de un sandbox?

Sí. Docker, Compose y Buildx están en `base`, y el daemon se inicia con el primer uso.

### ¿Un proceso en segundo plano mantiene despierto el sandbox?

No. Sobrevive a las pausas, y una petición a su puerto despierta el sandbox, pero solo las llamadas, las sesiones y los comandos `keep_awake` evitan que se pause.

[AnteriorBuenas prácticas para Pethost Agent Sandboxes](https://pethost.dev/es/docs/sandboxes/best-practices/) [SiguientePuertos y previsualizaciones: las URL de un sandbox](https://pethost.dev/es/docs/sandboxes/ports-and-previews/)

## Prueba Pethost Agent Sandboxes

Una prueba gratis de 7 días con 1 US$ de uso y 4 vCPU, con tarjeta. Después, un plan desde 20 US$ al mes, que incluye ese mismo importe en uso.

[Empezar la prueba gratis](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Plantillas](https://pethost.dev/es/templates/)
- [Sobre nosotros](https://pethost.dev/about/)
- [Docs](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/es/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [Términos](https://pethost.dev/terms/)
- [Privacidad](https://pethost.dev/privacy/)
- [Reembolsos](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Bases de datos

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

Agent Sandboxes

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

Comparativas

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/es/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/es/blog/coolify-cloud-vs-dokploy-cloud/)
- [Precios de Railway vs Render vs Fly.io](https://pethost.dev/es/blog/railway-vs-render-vs-fly-io-pricing/)
- [Hosting gestionado para Docker Compose](https://pethost.dev/es/blog/managed-docker-compose-hosting/)

Alternativas

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