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

> ## Agent Instructions
> Evolve has two products behind one API key. Edith answers questions about an agent trajectory over HTTP: `POST https://api.evolvingmachines.ai/v1/decisions`. Evaluations run coding agents on tasks in cloud sandboxes, through the `evolve` CLI, the Python and TypeScript SDKs, or HTTP.
> A person creates the key at https://dashboard.evolvingmachines.ai/api-keys. Read it from `EVOLVE_API_KEY`; never ask for it in chat or write it to a file.
> Install the CLI with `npm install -g @evolvingmachines/evolve`, then confirm the connection with `evolve auth status`.
> The CLI carries the manual for its own version. `evolve skills get evals` prints the index and `evolve skills get evals <page>` prints one page, for example `evolve skills get evals cli-reference/run`. When the installed CLI is older than this site, follow the installed manual.
> Commands take `--help` for their options and `--json` for machine-readable output. Evaluations spend credits: start with one task and set `--max-trial-spend`.

# Configure your agent

> Choose the harness, model, and sandbox, and give the agent files and skills.

Configure Evolve before the first run. This example gives Codex a sales CSV,
reporting instructions, and a reusable skill, then retrieves its report.

Complete the [SDK setup](https://docs.evolvingmachines.ai/agent-sdk/index.md) first, including installation and
`EVOLVE_API_KEY`. Run the example from your project directory.

## Add a reporting skill

A skill is a folder containing a `SKILL.md` file. Create
`skills/reporting/SKILL.md` with these contents:

```markdown skills/reporting/SKILL.md theme={"dark"}
---
name: reporting
description: Summarize sales data and check the arithmetic.
---

When preparing a sales report:
1. Calculate totals with code.
2. Include a table with each region and its sales.
3. State the overall total and the source file.
```

## Configure and run

`type` selects the harness, the CLI agent that works in the sandbox. `model`
selects the model it calls. See [models and effort levels](https://docs.evolvingmachines.ai/core-concepts/models.md)
for supported choices.

```typescript configure.mjs theme={"dark"}
import {
  Evolve,
  managedSandbox,
} from "@evolvingmachines/evolve";

const agent = new Evolve()
  .withAgent({
    type: "codex",
    model: "gpt-6-luna",
    reasoningEffort: "medium",
  })
  .withSandbox(await managedSandbox("e2b"))
  .withContext({
    "reporting.md": "All sales values are in USD. " +
      "Round to two decimals.",
  })
  .withFiles({
    "sales.csv": "region,sales\nNorth,1200\nSouth,950\n",
  })
  .withSkills([
    "./skills/reporting",
  ]);

try {
  await agent.run({
    prompt: [
      "Use the reporting skill to summarize sales.csv.",
      "Follow context/reporting.md.",
      "Write the report to output/report.md.",
    ].join(" "),
  });

  const output = await agent.getOutputFiles();
  console.log(output.files["report.md"]);
} finally {
  await agent.kill();
}
```

```python configure.py theme={"dark"}
import asyncio

from evolve import AgentConfig, Evolve, ManagedProvider


async def main():
    agent = Evolve(
        config=AgentConfig(
            type="codex",
            model="gpt-6-luna",
            reasoning_effort="medium",
        ),
        sandbox=ManagedProvider(
            provider="e2b",
        ),
        context={
            "reporting.md": (
                "All sales values are in USD. "
                "Round to two decimals."
            ),
        },
        files={
            "sales.csv": (
                "region,sales\n"
                "North,1200\n"
                "South,950\n"
            ),
        },
        skills=[
            "./skills/reporting",
        ],
    )

    try:
        await agent.run(
            prompt=(
                "Use the reporting skill "
                "to summarize sales.csv. "
                "Follow context/reporting.md. "
                "Write the report to output/report.md."
            ),
        )

        output = await agent.get_output_files()
        print(output.files["report.md"])
    finally:
        await agent.kill()


asyncio.run(main())
```

```bash TypeScript theme={"dark"}
node configure.mjs
```

```bash Python theme={"dark"}
python configure.py
```

The first `run()` creates the sandbox and uploads the files and skill. The
`finally` block destroys the sandbox after you retrieve the report, including
when a run fails.

## Choose where files go

File mappings use destination paths as keys and file contents as values.
Paths below are relative to the default `/home/user/workspace` directory.

| Input | TypeScript | Python | Destination |
| - | - | - | - |
| Reference material | `withContext()` | `context=` | `context/<path>` |
| Working files | `withFiles()` | `files=` | `<path>` |
| Agent deliverables | `getOutputFiles()` | `get_output_files()` | Reads `output/` |

The example sends file contents directly. To send a local file, read it in your
application and pass its text or binary contents in the same mapping.

## Choose a sandbox

The example explicitly selects managed E2B. Change `"e2b"` to `"daytona"` or
`"modal"` to use another managed provider with the same Evolve API key.

If you omit the sandbox configuration, Evolve selects a provider from your
environment:

| Credentials | Sandbox |
| - | - |
| `EVOLVE_API_KEY` only | Managed E2B |
| `E2B_API_KEY` | Your E2B account |
| `DAYTONA_API_KEY` | Your Daytona account |
| `MODAL_TOKEN_ID` and `MODAL_TOKEN_SECRET` | Your Modal account |

Your sandbox credentials take priority over managed E2B. If several provider
keys are set, selection order is E2B, Daytona, then Modal. Keep `EVOLVE_API_KEY`
set to continue using Evolve model access with your own sandbox account.

## Reuse other skills

Replace `"./skills/reporting"` with another local skill folder or a Git
reference, such as `"anthropics/skills"`. A whole repository reference loads
the skills it publishes; use a specific skill path when you only need one.

Skills mount in the selected harness's native skills directory. A local skill
folder must contain `SKILL.md`; a skill name alone is not a built-in catalog.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.