Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .agentenv/config.example.toml
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,11 @@ agent_default = "local" # agents too
# api_key = "secret:agent37_api_key" # or "env:AGENT37_API_KEY"
# region = "us" # or "eu", "ap-south"

# Optional kosa8 Cloud microVMs (no extra needed):
# [sandbox.providers.kosa8.config]
# api_key = "secret:kosa8_api_key" # or "env:KOSA8_API_KEY"
# region = "us" # optional: "us", "eu", "us-ash1" or "eu-hel1"

# Optional CoreWeave Sandboxes (install the 'coreweave' extra):
# [sandbox.providers.coreweave.config]
# api_key = "secret:cwsandbox_api_key" # or wandb_api_key, with optional wandb_entity and wandb_project
Expand Down
8 changes: 4 additions & 4 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,9 +71,9 @@ or one of them only where it is used.
store, an OCI registry at `localhost:5000`, env-var secret store, `LocalRunner`, `local` Docker
sandboxes for envs and agents. MongoDB, DynamoDB, Firestore, S3, Cloud Storage, ECR, AWS Secrets
Manager, Google Cloud Secret Manager, and the Modal, E2B, Sail, SmolVM, Tensorlake, Tenki, Vercel, boxd,
CoreWeave, Daytona, boat and Agent37 sandboxes exist as implementations and are selected by config (all but
Agent37 through their extras: `sail`, `smol`, `tensorlake`, `tenki`, `vercel`, `boxd`, `coreweave`, `daytona`,
`boat`; every extra but `smol` is in `dev`; Agent37 needs only `httpx`).
CoreWeave, Daytona, boat, Agent37 and kosa8 sandboxes exist as implementations and are selected by config (all but
Agent37 and kosa8 through their extras: `sail`, `smol`, `tensorlake`, `tenki`, `vercel`, `boxd`, `coreweave`, `daytona`,
`boat`; every extra but `smol` is in `dev`; Agent37 and kosa8 need only `httpx`).
- The model endpoint is unset until `[model] base_url` / `api_key` (or `LITELLM_BASE_URL` /
`LITELLM_API_KEY`) is configured. A loopback URL handed into a `local` container (the model
endpoint, an agent, peer or gateway on this machine) becomes `host.docker.internal`. On Linux that
Expand Down Expand Up @@ -128,7 +128,7 @@ and deserialized through a registry.
| `task/`, `task_step/` | A `Task` holds its `TaskStep`s inline; `Task.run()` executes them as a DAG. `depends_on` (None means all prior steps) gates a step, independent steps run concurrently, `fail_task_on_error` makes a failure fatal or tolerated, `retry_config` rolls a failed span back through the step journal and re-dispatches it. Built-in steps live in `task_step/task_steps/` (`deploy_env`, `deploy_agent`, `prompt_agent`, the verifiers under `verifiers/`, among them `start_computer_recording` and `end_computer_recording`, `start_browser_recording` and `end_browser_recording` (`browser-recording/v1`: one recording per context, a lease's or the default one's, with a video of the tab its agent is on, its context's log, the browser's network log as HAR and opt-in frames keyed to the action log, the contexts its agents make recorded with it, one universe per recording, anything missing failing the run), and more). On an env whose card serves computer-exec/v1 (a computer), `run_code` with `env_id` and `run_container_unit_tests_verifier` with `env_id` run inside it as its session user through the driver: files staged with `data/add` and read with `data/get`, commands run with `run`; `env_outcome_verifier` hands a `verify` that takes an `env_url` keyword the env's address. A computer's framework-only routes (everything but MCP and the card) take the per-deploy control token its provider boots it with (`DeployedEnv.control_token`, `AGENTENV_CONTROL_TOKEN`), a multi env's computers the multi env's own, which its gateway passes on only on their `/svc` routes and its clock watch (`CONTROL_TOKEN_CHILDREN`); framework calls send `deployed.control_headers`, `Task.run` runs every step under `protocol_v1.authorized` with each deployed env's (a `verify` included), and a `run_code` script inside the computer gets `input["env"]["headers"]`. `teardown_run` and the `teardown_sandboxes` step share one core (`task/teardown.py` `tear_down`): the recordings the run left open end with fresh grants, each env still up closes (`Env.close`; a computer env ends any recording still open), what stayed open is registered from its namespace, then every sandbox is terminated by id. `task/episode/` runs a task with some of its agents played from outside, as a training loop does (`EpisodeSpec`). |
| `store/` | Four store ABCs with local and cloud implementations: `DocumentStore` (SQLite, MongoDB, DynamoDB, Firestore with MongoDB compatibility), `ObjectStore` (filesystem, S3, Cloud Storage), `ImageStore` (local OCI registry, ECR), `SecretStore` (env vars or file, AWS Secrets Manager, Google Cloud Secret Manager). `VersionedEntityStore` implements the shared versioned get/put logic, `QueryBuilder` is the immutable chained query API, `store/base.py` holds the error types. `store/routing.py` is the local namespaces, `@local` and `@hf` (`is_local_id`), each with a documents file of its own: while the CLI or a `build_app` server runs, a local id and what a local task's run records go to local stores beside the configured ones, and that run's writes to the configured stores are refused. A new backend must pass the conformance kits in `tst/store/`. |
| `config/` | The `Config` singleton (`get_config`, `configure`, `reset_config`) in `config/runtime.py`, file discovery in `config/loader.py`, and `load_impl`, which resolves `module:Class` pointers. `agent_env.store` re-exports the config names for compatibility. |
| `providers/` | `providers/sandbox_providers/` holds the sandbox providers `local`, `modal`, `modal_vm`, `e2b`, `sail_vm` (the `sail` extra), `smol_vm` (the `smol` extra), `tensorlake` (the `tensorlake` extra), `tenki` (the `tenki` extra), `vercel` (the `vercel` extra), `boxd` (the `boxd` extra), `coreweave` (the `coreweave` extra), `daytona` (the `daytona` extra), `boat` (the `boat` extra), `agent37` (no extra); `[sandbox] default` and `agent_default` accept a comma-separated fallback chain, whose deploys skip a provider that can't run them. A sandbox provider declares what it runs (`ON_THIS_MACHINE`, and for VMs on this machine the address their requests to it arrive at, `REACHES_HOST_AT`; `CONTAINER_ACCEPTS`, `PRIVATE_NETWORK`, `WEBSOCKETS`; `SUPPORTED_SANDBOX_MODES`, derived from whether it implements `create_sandbox` and `create_vm`; and `SANDBOX_ACCEPTS`, the images an agent's sandbox runs, which defaults to those a VM loads when it implements `create_vm` and to `CONTAINER_ACCEPTS` otherwise, so only a provider that implements `create_vm` yet gives an agent a container, like the local one, declares it), each sandbox carries the `platform` of the images it runs (linux/amd64 unless its provider sets another when it creates it; None, any, unchecked, for a local sandbox), and code outside `providers/sandbox_providers/` reads those, never which provider it has. `providers/env_providers/` holds the environment providers: `EnvironmentProvider` (an env's containers and state store), `EnvironmentGatewayProvider` (`gateway`, an env's default), which renders a docker-compose for the gateway and its MCP servers inside the sandbox, and `EnvironmentServerProvider` (`server`), one MCP server in its own container with no gateway in front and no state store; `providers/env_state/` holds env-state providers (`local_postgres` built in). |
| `providers/` | `providers/sandbox_providers/` holds the sandbox providers `local`, `modal`, `modal_vm`, `e2b`, `sail_vm` (the `sail` extra), `smol_vm` (the `smol` extra), `tensorlake` (the `tensorlake` extra), `tenki` (the `tenki` extra), `vercel` (the `vercel` extra), `boxd` (the `boxd` extra), `coreweave` (the `coreweave` extra), `daytona` (the `daytona` extra), `boat` (the `boat` extra), `agent37` (no extra), `kosa8` (no extra); `[sandbox] default` and `agent_default` accept a comma-separated fallback chain, whose deploys skip a provider that can't run them. A sandbox provider declares what it runs (`ON_THIS_MACHINE`, and for VMs on this machine the address their requests to it arrive at, `REACHES_HOST_AT`; `CONTAINER_ACCEPTS`, `PRIVATE_NETWORK`, `WEBSOCKETS`; `SUPPORTED_SANDBOX_MODES`, derived from whether it implements `create_sandbox` and `create_vm`; and `SANDBOX_ACCEPTS`, the images an agent's sandbox runs, which defaults to those a VM loads when it implements `create_vm` and to `CONTAINER_ACCEPTS` otherwise, so only a provider that implements `create_vm` yet gives an agent a container, like the local one, declares it), each sandbox carries the `platform` of the images it runs (linux/amd64 unless its provider sets another when it creates it; None, any, unchecked, for a local sandbox), and code outside `providers/sandbox_providers/` reads those, never which provider it has. `providers/env_providers/` holds the environment providers: `EnvironmentProvider` (an env's containers and state store), `EnvironmentGatewayProvider` (`gateway`, an env's default), which renders a docker-compose for the gateway and its MCP servers inside the sandbox, and `EnvironmentServerProvider` (`server`), one MCP server in its own container with no gateway in front and no state store; `providers/env_state/` holds env-state providers (`local_postgres` built in). |
| `a2a_agent/` | The `A2AAgent` entity (`a2a_agent`), its stores and the validator steps. The protocol package provides the agent-side framework. |
| `openenv/` | `build_app(bundle)`: the [OpenEnv](https://github.com/openenv/OpenEnv) server for a bundle's tasks, each session playing one episode through the Episode API, with the envs' MCP tools, an added `end_turn` tool and the task's verifier score as the reward. It prepares bundles as `agent-env run` does (`prepare_bundle(played=True)`, without the agent the client plays) and keeps namespace routing on for the app's life. `openenv` comes with the `openenv` extra, a floor with no cap; this package and `training/` are the only ones that import it. Each task's description in the Task API names its `toolset` (the played agent's envs, role, and whether it gets `bash`). With `token`, every request and WebSocket but `/health` must carry `Authorization: Bearer <token>`, for a server others reach. |
| `training/` | One module per outside trainer, each behind its own extra, and the modules they share; [Training helpers](#training-helpers) lists them. |
Expand Down
2 changes: 1 addition & 1 deletion src/agent_env/cli/a2a_agent/deploy.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
@click.option("--ttl-seconds", type=click.IntRange(min=MIN_TTL_SECONDS, max=MAX_TTL_SECONDS), default=DEFAULT_TTL_SECONDS,
help=f"VM lifetime in seconds (default {DEFAULT_TTL_SECONDS})")
@click.option("--sandbox", default=None,
help="Sandbox backend(s): a built-in (modal, modal_vm, e2b, tensorlake, tenki, boxd, coreweave, daytona, boat, agent37, local) "
help="Sandbox backend(s): a built-in (modal, modal_vm, e2b, tensorlake, tenki, boxd, coreweave, daytona, boat, agent37, kosa8, local) "
"or a name from [sandbox.providers] in .agentenv/config.toml; comma-separated for a "
"fallback chain. Defaults to [sandbox].agent_default (else local) when omitted.")
def deploy(agent_id: str, agent_version: int | None, env_var_pairs: tuple[str, ...], ttl_seconds: int, sandbox: str):
Expand Down
2 changes: 1 addition & 1 deletion src/agent_env/cli/env/deploy.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
@click.option("--gateway-mode", type=click.Choice([m.value for m in GatewayMode], case_sensitive=False),
default=GatewayMode.PERFORMANCE.value, help="Gateway mode (performance or consistent)")
@click.option("--sandbox", default=None,
help="Sandbox backend(s): a built-in (modal, modal_vm, e2b, tensorlake, tenki, boxd, coreweave, daytona, boat, agent37, local) "
help="Sandbox backend(s): a built-in (modal, modal_vm, e2b, tensorlake, tenki, boxd, coreweave, daytona, boat, agent37, kosa8, local) "
"or a name from [sandbox.providers] in .agentenv/config.toml; comma-separated for a "
"fallback chain. Defaults to [sandbox].default (else local) when omitted.")
@click.option("--service-db", "service_db_env_id", default=None,
Expand Down
129 changes: 129 additions & 0 deletions src/agent_env/providers/sandbox_providers/kosa8/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,129 @@
# `kosa8` sandbox provider

Runs agent-env sandboxes on [kosa8 Cloud](https://kosa8.com). Each environment and each agent gets its own microVM,
booted with Docker inside and a public HTTPS URL for each of its ports. It is a VM provider: agent-env's docker-in-VM
flows run on it unchanged. That covers the gateway's docker-compose, an agent's `docker run`, image loading and
artifact collection.

## Set up

### 1. No extra to install

The provider drives kosa8's REST API with `httpx`, which agent-env already depends on.

### 2. Get a kosa8 API key

Create a key in the [dashboard](https://app.kosa8.com) under API keys, with the `sandboxes:read` and `sandboxes:write`
scopes. Sandboxes booted at a size, as these are, need a payment method on the organization. For local work, export
it:

```bash
export KOSA8_API_KEY=...
```

For a shared deployment, put it in your secret store instead, for example as `kosa8_api_key`, and reference it with
`secret:kosa8_api_key`. Never put the key itself in `config.toml`. The provider reads the key only from its config,
never from the process environment.

### 3. Configure

A complete `.agentenv/config.toml` that runs every environment and agent on kosa8, with the local stores:

```toml
[sandbox]
default = "kosa8" # environments and sandboxes
agent_default = "kosa8" # agents

[sandbox.providers.kosa8.config]
api_key = "env:KOSA8_API_KEY" # or "secret:kosa8_api_key"

[model]
base_url = "https://litellm.example.com"
api_key = "env:LITELLM_API_KEY"
```

To keep the local default and use kosa8 per run instead, add only the `[sandbox.providers.kosa8.config]` table and
pass `--sandbox kosa8`, or `--env-sandbox kosa8` / `--agent-sandbox kosa8` on `agent-env task run`.

### 4. Run something

```bash
agent-env run hello --sandbox kosa8
```

`agent-env -v run …` also logs each sandbox as it starts
(`kosa8 sandbox started: id=… name=… size=… disk_gb=… ttl_s=… ports=… attribution=…`).

## Configuration reference

All keys go under `[sandbox.providers.kosa8.config]`. Unknown keys are refused.

| Key | Default | Meaning |
| ---------- | ------------------------------------------ | -------------------------------------------------------------------------- |
| `api_key` | required | The kosa8 API key, as an `env:` or `secret:` reference. |
| `base_url` | `https://api.kosa8.com` | The kosa8 control plane. |
| `region` | the organization's default | `us`, `eu`, or a region such as `us-ash1` or `eu-hel1`. |
| `image` | `kosa8-template/universal-24.04-20261115.2` | The sandbox's own image. It must ship `dockerd` and the Compose v2 plugin. |

## Resources and lifetime

- **Sizes:** kosa8 has four: 2 vCPU / 4 GiB, 4 / 8, 8 / 16 and 16 / 32. A request gets the smallest that covers both
its CPU and its memory, so agent-env's default (1 vCPU, 8 GiB) runs on 4 vCPU / 8 GiB. A larger request is refused
before anything is created, not shrunk.
- **Disk:** the request's disk, at least 32 GB (kosa8's default, which holds the images Docker pulls) and at most
200 GB; a larger request is refused.
- **Ignored requests:** `boot_mode` and `env` have no kosa8 equivalent here; one that is set logs a warning.
- **Lifetime:** the sandbox's `timeout` is its `ttl_s` (60 s to 90 days), so kosa8 deletes it then even if a crashed
run never tears it down.
- **Sleep:** `sleep_after_s` is 0, so a sandbox never sleeps while agent-env uses it.

## Networking

- **Ports:** each exposed port is a public kosa8 preview, `https://<port>-<random>.kosa8labs.com`, which fills
`tunnel_urls`. It serves HTTP and WebSocket with no platform authentication, like other providers' tunnels; the
random part is the only secret.
- **Egress:** allow-all, or an allow list of at most 256 hostnames, `*.` wildcards and IPv4 addresses or ranges. kosa8
enforces it on the host, outside the VM, so one list covers `dockerd` and every container. The list goes with the
create, so it is in force before kosa8 answers and the sandbox never runs more open than asked. IPv6 entries are
refused with `NetworkPolicyUnsupportedError` before anything is created; a list kosa8 itself refuses (or an
organization policy that does not allow it) fails the create with the same error, so a fallback chain moves on.
- **Wildcards:** `*.example.com` covers every name under `example.com` but not `example.com` itself.
- **kosa8's own hosts:** `*.kosa8labs.com` is added to every allow list, so a restricted agent can reach the
environments it talks to.
- **Organization policy:** an organization's default egress policy applies to sandboxes that set none, and the
sandbox's `network_policy` reports what kosa8 enforces. A deny-only policy reads as allow-all; the sandbox keeps
its denies, and a file whose signed URL is on a denied host is pushed over exec rather than downloaded.
- **Reconnect:** `get_sandbox` restores the ports and the applied policy from kosa8.

## Cleanup

- A sandbox whose setup fails after it is created (boot, ports, Docker readiness) is deleted.
- If a create fails after kosa8 may have made the sandbox, or its caller is cancelled, the provider finds it by its
unique `agentenv-<random>` name and deletes it.
- Whatever else happens, `ttl_s` removes the sandbox at the sandbox's `timeout`.
- `terminate` is idempotent: a sandbox that is already gone is not an error.

## Things to know

- **Commands run as root**, so the `sudo` agent-env prefixes is dropped, and read no input (standard input is
`/dev/null`).
- **Long commands:** exec is streamed, which no time limit holds; kosa8 sends a heartbeat every 15 s while a command
is quiet.
- **Lost connections:** when a command's stream ends without an exit status, `exec` returns exit code -1.
`exec_script` retries idempotent scripts on -1 only. A call kosa8 refused before the command started (`409
starting`, `429`, `503`) is resent.
- **Large commands:** kosa8 takes at most 256 arguments of 8 KiB each. A longer command is uploaded to
`/workspace/.agentenv` through the files API and read back as its argument list.
- **Files:** `write_host_file` uploads through the files API, which reaches only `/workspace`, in 4 MiB pieces, then
moves the bytes into place, so a secret never enters a command line.
- **Images:** `create_vm(image=...)` is refused. Sandboxes boot the configured image, and OCI images run under Docker
inside them.
- **Platform:** linux/amd64. GPUs are not supported.
- **The model key enters the sandbox:** an agent's `LITELLM_API_KEY` is passed in, as on other providers.

## Testing

`tst/integration/providers/sandbox_providers/kosa8_sandbox_smoke_test.py` runs against a real kosa8 organization when
`[sandbox.providers.kosa8.config]` resolves. Otherwise it skips with `agentenv-capability-missing: remote_sandbox`.
The unit tests are `tst/unit/providers/sandbox_providers/kosa8_sandbox_provider_test.py` and `kosa8_sandbox_test.py`,
and run offline against an in-memory kosa8 API behind `httpx.MockTransport`.
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
"""kosa8 Cloud sandbox provider (no extra: it drives kosa8's REST API with ``httpx``); see README.md."""
Loading
Loading