---
title: "Befehle ausführen und Dateien bearbeiten in einer Sandbox | Pethost Agent Sandboxes"
description: "Shell-Befehle in einer Sandbox ausführen und auf Ausgabe oder Port warten, lange streamen, Dateien durch exaktes Ersetzen bearbeiten, große über Links bewegen."
---

[Doku zu Agent Sandboxes](https://pethost.dev/de/docs/sandboxes/) · Aufgaben

# Befehle ausführen und Dateien bearbeiten in einer Sandbox

Aktualisiert 22. November 2026 · 9 Min. Lesezeit

Führ einen Befehl in einer Sandbox aus und bekomm seine Ausgabe und seinen Exit-Code in einem Aufruf, folge einem langen, während er läuft, bearbeite Dateien durch exaktes Ersetzen, bewege Dateien jeder Größe über Links und öffne ein Terminal im Browser.

**Kurz gesagt**

- **`RunCommand`** führt `bash -lc` als `user` in `/home/user` aus und wartet bis zu 45 s: sein Exit-Code und die letzten 32 KiB seiner Ausgabe, oder RUNNING mit seiner ID.
- **`WatchCommand`** streamt die Ausgabe eines Befehls, wie sie kommt; `GetCommand` wartet erneut und liest nur das Neue.
- **`WriteFiles`** schreibt, bearbeitet, verschiebt und löscht Dateien in einem Aufruf, der Reihe nach; eine Bearbeitung ersetzt Text, der genau einmal vorkommt.
- **Links** bewegen Dateien jeder Größe und öffnen ein Terminal im Browser.

Die Beispiele schließen an den [Schnellstart](https://pethost.dev/de/docs/sandboxes/quickstart/) an: `sandboxes` (`client` in Go) ist ein Client, und die ID der Sandbox liegt bereit.

### Step 1: Befehl ausführen

Ein Befehl ist ein String, ausgeführt von `bash -lc`, also funktionieren Pipes, `&&` und Variablen. `cwd` und `user` ändern, wo und als wer er läuft; `user` ist `root` oder der Standard, `user`, der sudo ohne Passwort hat.

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: Einem langen Befehl folgen

Mit `wait_seconds` 0 antwortet der Aufruf, sobald der Befehl gestartet ist. `WatchCommand` schickt dann seine Ausgabe ab den letzten 64 KiB, wie sie kommt, und den Befehl, wie er zuletzt endete.

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

Ohne Stream wartet `GetCommand` erneut bis zu 45 s. Gib die `stdout_bytes` der zuletzt gelesenen Antwort als `stdout_after_bytes` mit, und es schickt nur, was danach kam.

### Step 3: Dateien schreiben, bearbeiten und lesen

`WriteFiles` nimmt eine Liste von Änderungen und macht sie der Reihe nach: `text` oder `data` schreibt eine ganze Datei (mit `mode`, sonst `0644`), `edit` ersetzt ein exaktes Stück einer Datei, `move_to` verschiebt sie, `delete` löscht eine Datei oder ein Verzeichnis, `make_directory` legt eins an. Fehlende Verzeichnisse werden angelegt, und der Stapel hält bei der ersten Änderung an, die scheitert.

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: Große Datei über einen Link bewegen

Ein Aufruf trägt 1 MiB, `WriteFiles` 17 MiB und `ReadFile` 1 MiB. Eine Datei jeder Größe geht stattdessen über einen Link: `CreateLink` mit `download_path` gibt eine URL für ein GET, ein Verzeichnis kommt als .tar; mit `upload_path` eine URL, an die du die Bytes der Datei per PUT schickst. Jeder funktioniert einmal und geht direkt an den Server der 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: Terminal im Browser öffnen

`CreateLink` mit `terminal` gibt eine Seite mit einer Shell in der Sandbox, in die eine Person tippen kann; sein `command` führt statt der Shell ein Programm aus, etwa `claude`. Ein WebSocket an dieselbe URL trägt die Bytes des Terminals in beide Richtungen, für ein eigenes Terminal.

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:~$
```

Ein Link läuft nach einer Stunde ab, außer `ttl_seconds` sagt etwas anderes, höchstens 86.400 s, und trägt ein Token in seiner URL: Gib ihn der Person, die ihn nutzt, nie einer Seite, die andere lesen. Ihn zu erstellen weckt nichts.

## Wo ein Befehl läuft

Ein Befehl läuft in der VM der Sandbox als `user` (uid 1000, sudo ohne Passwort, in der Gruppe `docker`) in `/home/user`, oder als `root`. Seine Umgebung ist die der Vorlage, darüber die eigenen Variablen der Sandbox (`settings.environment`). `stdin` gibt ihm eine Eingabe, die danach geschlossen wird. Ein Befehl läuft, bis er endet, bis `timeout_seconds` oder bis `StopCommand`: Das Warten des Aufrufs endet, der Befehl nicht.

Ein Aufruf in eine pausierte Sandbox weckt sie zuerst, in etwa 80 ms. Ein Hintergrundprozess, der weiterläuft (ein Server, mit `&` gestartet), übersteht Pausen, hält die Sandbox aber nicht von selbst wach: Starte einen langen Job mit `keep_awake`, damit der Pause-Timer auf ihn wartet ([keep_awake](https://pethost.dev/de/docs/sandboxes/lifecycle/#keep-awake)).

## Ausgabe, Offsets und Verlauf

Eine Antwort hält die letzten 32 KiB von stdout und von stderr, als UTF-8, mit `output_truncated`, wenn der Anfang abgeschnitten wurde, und `stdout_bytes` und `stderr_bytes`, alles, was geschrieben wurde. `exit_code` ist der der Shell: 128 plus die Nummer des Signals, wenn ein Signal ihn beendet hat, und fehlt, solange er läuft. Die Sandbox behält ihre letzten 100 beendeten Befehle für `GetCommand`. `ListCommands` listet die, die gerade laufen, gestartet über die API, über SSH oder in einem Terminal.

`StopCommand` schickt SIGTERM und 10 s später SIGKILL, wenn der Befehl noch läuft. Für einen beendeten Befehl aufgerufen, beendet es, was dieser Befehl im Hintergrund laufen ließ.

## Bearbeiten durch exaktes Ersetzen

Ein `edit` ersetzt `old_text` durch `new_text`, wo `old_text` genau einmal in der Datei vorkommt, die höchstens 16 MiB groß ist. Nicht vorhanden ist `EDIT_NOT_FOUND`; zweimal oder öfter ist `EDIT_AMBIGUOUS`, und die Datei bleibt in beiden Fällen unverändert. Das ist die Bearbeitung, die Coding-Agenten machen, und sie scheitert laut, wo eine Zeilennummer veraltet gewesen wäre. Ein Schreiben ersetzt eine ganze Datei und behält ihren Besitzer und Modus; es schreibt durch einen symbolischen Link in sein Ziel.

`WatchFiles` streamt, was unter einem Verzeichnis erstellt, geschrieben, entfernt und umbenannt wird, mit `recursive` auch darunter. `OVERFLOW` sagt, dass Events verloren gingen: Liste das Verzeichnis neu.

## Docker in einer Sandbox

Jede Sandbox aus `base` hat Docker, mit Compose und Buildx. Sein Daemon startet bei der ersten Verbindung zu `/var/run/docker.sock` und kostet bis dahin nichts. Images und Container liegen auf der Disk der Sandbox, also behält ein Stopp sie, und eine Vorlage nimmt sie mit. Pulls von Docker Hub gehen zuerst über einen Mirror.

## Wenn es nicht funktioniert

- **Die Antwort ist RUNNING, ohne Exit-Code:** Der Befehl hat länger als `wait_seconds` gedauert und läuft weiter. Folge ihm mit `WatchCommand` oder warte mit `GetCommand`.
- **Die Sandbox hat mitten in einem langen Build pausiert:** Nichts hat sie aufgerufen, während der Build lief. Starte solche Arbeit mit `keep_awake` und einem `timeout_seconds`.
- **`failure` ist `EDIT_NOT_FOUND` oder `EDIT_AMBIGUOUS`:** Lies die Datei neu und schick ein `old_text`, das einmal vorkommt; die Änderungen davor im Stapel wurden gemacht (`done_count`).
- **`RESOURCE_EXHAUSTED` ohne `LimitReached`:** Der Request lag über seiner Grenze (eine Datei über 17 MiB: Nimm einen Upload-Link), oder die Sandbox bedient schon 64 Aufrufe gleichzeitig. Beende einen, oder warte.
- **`FAILED_PRECONDITION` mit `Stopped`:** Die Sandbox ist gestoppt. `ResumeSandbox` startet sie, ihre Dateien, wie sie sie verlassen hat.
- **Ein Befehl, der RUNNING war, ist `LOST`:** Die Sandbox hat ihren RAM verloren (sie wurde gestoppt), während der Befehl lief. Führ ihn noch einmal aus.

## Fragen

### Wie lange kann ein Befehl laufen?

So lange er braucht: Der Aufruf wartet bis zu 45 s, und der Befehl läuft weiter. Nur `timeout_seconds` oder `StopCommand` beenden ihn früher.

### Kann ich Befehle als root ausführen?

Ja: `user` `root`, oder `sudo`, das `user` ohne Passwort hat.

### Wie lade ich eine große Datei in eine Sandbox hoch?

`CreateLink` mit `upload_path` gibt eine URL, an die du die Datei per PUT schickst, in jeder Größe, oder `pethost sandbox cp` erledigt das für dich.

### Kann ich Docker in einer Sandbox ausführen?

Ja. Docker, Compose und Buildx sind in `base`, und der Daemon startet bei der ersten Nutzung.

### Hält ein laufender Hintergrundprozess die Sandbox wach?

Nein. Er übersteht Pausen, und ein Request an seinen Port weckt die Sandbox, aber nur Aufrufe, Sitzungen und `keep_awake`-Befehle verhindern, dass sie pausiert.

[ZurückBest Practices für Pethost Agent Sandboxes](https://pethost.dev/de/docs/sandboxes/best-practices/) [WeiterPorts und Vorschauen: die URLs einer Sandbox](https://pethost.dev/de/docs/sandboxes/ports-and-previews/)

## Pethost Agent Sandboxes ausprobieren

Eine Testphase von 7 Tagen mit 1 $ Verbrauch und 4 vCPUs, mit Karte. Danach ein Tarif ab 20 $ im Monat, der genauso viel Verbrauch enthält.

[Testphase starten](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Vorlagen](https://pethost.dev/de/templates/)
- [Über uns](https://pethost.dev/about/)
- [Doku](https://pethost.dev/docs/)
- [Blog](https://pethost.dev/de/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Plugin](https://github.com/pethost-dev/plugin)
- [AGB](https://pethost.dev/terms/)
- [Datenschutz](https://pethost.dev/privacy/)
- [Erstattung](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Datenbanken

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

Agent Sandboxes

- [Sandboxes](https://pethost.dev/de/sandboxes/)
- [Preise](https://pethost.dev/de/sandboxes/#pricing)
- [Doku](https://pethost.dev/de/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Vergleiche

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

Alternativen

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