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

# Run agents from code

> Run a coding agent in a sandbox, read its output, and release the sandbox from Python or TypeScript.

Run Codex or another coding agent in a cloud sandbox from your application.
Give it a prompt, collect the files it creates, and continue the conversation
when you need another turn.

For scored runs against a dataset, use the [evaluation SDK](https://docs.evolvingmachines.ai/sdk-reference/index.md).

## Install

```bash TypeScript / JavaScript theme={"dark"}
npm install @evolvingmachines/evolve
```

```bash Python theme={"dark"}
pip install evolvingmachines-evolve
```

Use Node.js 18 or later. Python also requires Python 3.10 or later and Node.js,
because the direct-agent SDK uses a Node bridge.

## Set your API key

Create a key on the [dashboard](https://dashboard.evolvingmachines.ai/api-keys)
and export it in the terminal where you will run the example:

```bash theme={"dark"}
export EVOLVE_API_KEY="your-api-key"
```

With only this key, Evolve supplies model access and an E2B sandbox. If your
environment contains sandbox provider credentials, they take precedence.
See [sandbox configuration](https://docs.evolvingmachines.ai/agent-sdk/configure.md).

## Run one agent

This example starts a billable run and asks Codex to write a release note.
The `finally` block destroys the sandbox after the output is read.

> [tab] TypeScript / JavaScript
>
> Save as `run.mjs`. The example uses the TypeScript SDK from JavaScript,
> so it runs directly with Node.
>
> ```javascript run.mjs theme={"dark"}
> import { Evolve } from "@evolvingmachines/evolve";
>
> const agent = new Evolve().withAgent({
>   type: "codex",
>   model: "gpt-6-luna",
> });
>
> try {
>   const result = await agent.run({
>     prompt: "Write a release note for CSV export " +
>       "to output/notes.md.",
>   });
>   if (result.exitCode !== 0) {
>     throw new Error(result.stderr || "Agent run failed");
>   }
>   const output = await agent.getOutputFiles();
>   console.log(output.files["notes.md"]);
> } finally {
>   await agent.kill();
> }
> ```
>
> ```bash theme={"dark"}
> node run.mjs
> ```

> [tab] Python
>
> Save as `run.py`.
>
> ```python run.py theme={"dark"}
> import asyncio
> from evolve import AgentConfig, Evolve
>
> async def main():
>     agent = Evolve(config=AgentConfig(
>         type="codex",
>         model="gpt-6-luna",
>     ))
>     try:
>         result = await agent.run(
>             prompt="Write a release note for CSV export "
>                    "to output/notes.md.",
>         )
>         if result.exit_code != 0:
>             raise RuntimeError(
>                 result.stderr or "Agent run failed"
>             )
>         output = await agent.get_output_files()
>         print(output.files["notes.md"])
>     finally:
>         await agent.kill()
>
> asyncio.run(main())
> ```
>
> ```bash theme={"dark"}
> python run.py
> ```

The program prints the generated Markdown. The wording varies by run.
`output.files` maps file names to their contents; paths are relative to the
sandbox's `output/` directory.

## Continue building

* [Configure an agent](https://docs.evolvingmachines.ai/agent-sdk/configure.md): choose a model and provide files,
  skills, and tools.
* [Continue and inspect runs](https://docs.evolvingmachines.ai/agent-sdk/sessions.md): keep context, save state,
  and download traces.
* [Run work in parallel](https://docs.evolvingmachines.ai/agent-sdk/parallel-work.md): process multiple inputs
  with Swarm.


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