> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lazycloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a coding agent in a sandbox

> Keep model credentials and network access away from the code an agent writes.

A function calls your OpenAI-compatible provider and returns one validated
file replacement. A network-blocked sandbox receives only the seed project and
that replacement, then runs the unit test. The orchestrator terminates the
sandbox whether the test passes, fails, or errors.

The downloaded project contains the source and seed files under
`sandboxed_coding_agent/`.

The CLI installs once with `uv tool install lazycloud-client`. The commands
below download a standalone project and install its dependencies, with no
repository checkout. The rest of the guide runs from that directory through
`uv run`, which uses the project's pinned SDK.

```bash theme={null}
lazycloud example download sandboxed-coding-agent
cd sandboxed-coding-agent
uv sync
uv run lazycloud login
```

## What runs where

The deployed `plan-patch` function receives the provider base URL, model,
and API key as workspace secrets. The `test-patch` sandbox runs the generated
code with `block_network=True`.

The sandbox has no secrets, no outbound network, no exposed ports, and no
retained filesystem. The local orchestrator validates the planner's result
again before uploading anything.

The patch contract accepts complete UTF-8 content for `calculator.py` only.
It rejects absolute and traversal paths, unapproved or duplicate files,
control characters, more than three files, and more than 12,000 bytes. The
model cannot modify the test.

## Configure a provider

You need your provider's HTTPS base URL ending in `/v1`, a model name, and an
API key. The example appends `/chat/completions` itself.

```bash theme={null}
export CODING_AGENT_BASE_URL="https://provider.example/v1"
export CODING_AGENT_MODEL="provider-model-name"
read -rsp "Provider API key: " CODING_AGENT_API_KEY && echo
export CODING_AGENT_API_KEY

uv run python -m sandboxed_coding_agent.configure
unset CODING_AGENT_BASE_URL CODING_AGENT_MODEL CODING_AGENT_API_KEY
```

`configure.py` reads the names from the app's `PROVIDER_SECRET_NAMES` and stores
their environment values with `Secret(name).set(value)`. Running it again
replaces the stored values. The planner declares
`secrets=list(PROVIDER_SECRET_NAMES)`, and the sandbox declares none. Keep the
key out of the prompt, URLs, and source files.

<Warning>
  The planner sends the prompt and the seed source files to the provider you
  configure. Check that provider's data handling terms before pointing it at
  proprietary code.
</Warning>

## Deploy and run

Deploying the app deploys the planner. The orchestrator creates a sandbox for
each run.

```bash theme={null}
uv run lazycloud deploy sandboxed_coding_agent.app:app
uv run lazycloud run sandboxed_coding_agent.app:run_agent
```

The default prompt asks the planner to fix the deliberately broken
`calculator.add` without changing its test. The result includes the planner
task ID, the terminated sandbox ID, changed paths, the test exit code, test
output, and `tests_passed`. A successful repair returns `tests_passed: true`
and `test_exit_code: 0`. The command leaves your local seed project unchanged.

Pass a different instruction as the first argument:

```bash theme={null}
uv run lazycloud run sandboxed_coding_agent.app:run_agent "Correct calculator.add and preserve its type hints."
```

## If the repair fails

```bash theme={null}
uv run lazycloud task show <planner-task-id>
uv run lazycloud task logs <planner-task-id>
uv run lazycloud run sandboxed_coding_agent.app:inspect_sandboxes 20
```

Use the returned planner task ID to investigate provider failures. A failed
provider request creates no sandbox. For a failing test, read `test_output`
and revise the instruction. `test_exit_code` is the test process's exit code.
The CLI command can complete while the test fails, so check `tests_passed`.
The orchestrator terminates its sandbox in a `finally` block.

## Adapt the example

Each run costs your provider's tokens plus a short planner function and one
CPU sandbox. The seed project is tiny. Costs grow with source size, model
pricing, and retries.

To work on another project, change the seed files and the list of allowed
patch paths. Keep tests outside the model's editable files. Review generated
changes before applying them to a real repository. A passing test proves only
what that test checks.

## Clean up

The orchestrator terminates its sandbox. Delete the planner deployment and
the three secrets:

```bash theme={null}
uv run lazycloud deployment delete plan-patch
uv run lazycloud secret delete CODING_AGENT_BASE_URL
uv run lazycloud secret delete CODING_AGENT_MODEL
uv run lazycloud secret delete CODING_AGENT_API_KEY
```