---
title: "Work inside the sandbox you already grew."
description: "Run bounded commands and read or write UTF-8 and base64 files in an existing persistent Wildflower Computer sandbox."
canonical: "https://wildflower.computer/docs/commands-and-files/"
openapi_version: "0.8.0"
source_revision: "788b7325a454b8b753a7d614247d5694bad5c967"
---

# Work inside the sandbox you already grew.

Commands and files operate on an existing sandbox ID. They do not create a replacement environment, so filesystem changes remain available to later calls for the lifetime of that provider sandbox.

## Run a command

Supply a shell command plus an optional existing working directory and per-command environment. The environment map applies only to this command; it is not a durable secret store.

```bash
curl --fail-with-body --request POST \
  "$WILDFLOWER_URL/v1/sandboxes/$SANDBOX_ID/exec" \
  -H "Authorization: Bearer $WILDFLOWER_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "command": "printf hello && exit 7",
    "cwd": "/tmp",
    "env": { "FLOWER_COLOR": "orange" }
  }'
```

> **A non-zero exit is still an API success**
>
> A completed process returns HTTP success with `exitCode`,`stdout`, and `stderr`. Check the exit code in your application. Some providers expose only combined output; their adapter returns that text in `stdout` and an empty`stderr`.

## Write, then read a file

The destination parent directory must already exist. Read and write use the same generated `FileEncoding` choices:`utf8 and base64`. UTF-8 is the default. Use base64 when arbitrary bytes must survive JSON.

```bash
curl --fail-with-body --request POST \
  "$WILDFLOWER_URL/v1/sandboxes/$SANDBOX_ID/files/write" \
  -H "Authorization: Bearer $WILDFLOWER_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"path":"/tmp/hello.txt","content":"hello","encoding":"utf8"}'

curl --fail-with-body --request POST \
  "$WILDFLOWER_URL/v1/sandboxes/$SANDBOX_ID/files/read" \
  -H "Authorization: Bearer $WILDFLOWER_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"path":"/tmp/hello.txt","encoding":"utf8"}'
```

## Choose the right primitive

### Command

Best for tools, pipelines, package managers, and operations whose exit code matters.

- [Command operation reference](https://wildflower.computer/docs/reference/run-sandbox-command/)

### Write file

Best when your application already has bounded content and needs an exact destination path.

- [Write operation reference](https://wildflower.computer/docs/reference/write-sandbox-file/)

### Read file

Best for retrieving one bounded result without parsing command output.

- [Read operation reference](https://wildflower.computer/docs/reference/read-sandbox-file/)

## Keep provider access available

A connected project profile lets later processes address the sandbox using only the Wildflower bearer key. If you created it with an inline provider credential, a new process must receive that provider access and any required connection context again.