Skip to content

feat(sandbox): add a kosa8 Cloud sandbox provider - #754

Merged
earakely-scale merged 3 commits into
mainfrom
edgararakelyan/kosa8-sandbox-provider
Nov 18, 2026
Merged

earakely-scale merged 3 commits into
mainfrom
edgararakelyan/kosa8-sandbox-provider

Conversation

@earakely-scale

@earakely-scale earakely-scale commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

What

Adds kosa8, a built-in VM sandbox provider for kosa8 Cloud. Each env and each agent gets its own kosa8 microVM, booted with Docker inside and a public HTTPS preview URL per exposed port, so the docker-in-VM flows run unchanged: the gateway's docker-compose, an agent's docker run, image loading and artifact collection.

This is @drvt69talati's branch from #737. Their commit is kept as is, with their authorship, and two commits of mine follow it. Closes #737.

How it fits the other providers

It follows agent37, the other provider with no extra:

  • Package: providers/sandbox_providers/kosa8/ (provider.py, sandbox.py, README.md).
  • Dependencies: it drives kosa8's REST API with httpx, so there's no new extra and no uv.lock change.
  • Registration: an entry in _BUILTIN_SANDBOX_PROVIDERS, and the root AGENTS.md provider lists, the CLI --sandbox help, config.example.toml and tst/util/capabilities.py each name it.
  • Shared tests:
    • FACTORIES in network_policy_stamping_test.py, a row in provider_capabilities_test.py, its tunnel domain in egress_hosts_test.py, and config tests in test_config_sandbox_providers.py;
    • the gateway, task-step and WebSocket e2e tests take it as a parameter, gated by skip_without_remote_sandbox("kosa8"), as the other remote providers are.
  • Config: credentials come only from [sandbox.providers.kosa8.config] (api_key = "env:..." or "secret:..."), never from os.environ. TLS is always verified. Unknown config keys are refused.

What it does, as the sandbox-provider guide's checklist asks:

  • VM shape: it implements create_vm, get_sandbox and a VmSandbox; create_sandbox wraps create_vm, as boxd's does.
  • Requests it can't meet: a size larger than kosa8's largest, a disk over 200 GB or a per-call image is refused before anything is created. boot_mode and env are logged and ignored.
  • Network policy: an unenforceable policy is refused with NetworkPolicyUnsupportedError; IPv6 entries, or more than 256, are refused before any call.
  • Cleanup: a sandbox whose setup fails is deleted before the error is raised. A create whose answer was lost, or whose caller was cancelled, is found by its unique agentenv-<random> name and deleted. ttl_s backs both.
  • Reconnect: get_sandbox from a fresh provider restores the preview URLs and the egress policy kosa8 enforces. terminate is idempotent, and a gone sandbox raises SandboxNotFoundError.

My change on top

The contributor's version applied the egress allowlist with a PUT …/egress once the VM was running. kosa8 Cloud's create call takes the same allowlist (egress: {"allow": [...]}), and its docs say "the policy is in force before the create answers". If the host can't apply it, the sandbox is deleted and the create fails. So the allowlist now goes with the create, and a restricted sandbox never runs unrestricted.

A create kosa8 refuses because of its allowlist is raised as NetworkPolicyUnsupportedError, so a fallback chain moves on. That covers an egress error code such as 403 egress_not_allowed, and a 501. Any other refusal is raised as it is. The PUT and its API method are gone, and the README says the policy is applied at create.

A second fix, from review: kosa8 compiles an organization's deny rules into its enforced policy, either a block:… list or a ;deny:… part after an allow list, and NetworkPolicy can't hold either. Read as allow-all, a sandbox would try to curl a signed URL that kosa8's host blocks, and the load would fail instead of pushing the bytes over exec. The sandbox now keeps the denied entries beside its network_policy, from the create and from get_sandbox, and downloads only from a host its policy allows and nothing denies.

Verification

  • ruff check .: passes.
  • The kosa8 unit tests and the shared provider tests it touches (kosa8_sandbox_provider_test.py, kosa8_sandbox_test.py, egress_hosts_test.py, network_policy_stamping_test.py, provider_capabilities_test.py, test_config_sandbox_providers.py, tst/unit/test_capabilities.py): all pass. The one skip is the existing smol extra, which dev leaves out.
  • The integration modules collect with their kosa8 cases: the smoke test, the WebSocket test, the gateway tests and the task-step e2e.
  • check_plugin_api.py with this title: no break to the plugin surface.
  • CI: all 36 checks green on 6d1dc94.

Not run here: anything against a real kosa8 organization. kosa8 Cloud has no free tier, and CI uses no outside credentials, so its live tests skip with agentenv-capability-missing: remote_sandbox. @drvt69talati, could you run these on your org against this branch and paste the output?

agent-env run hello --sandbox kosa8
pytest tst/integration/providers/sandbox_providers/kosa8_sandbox_smoke_test.py -v

Docs

The website's provider pages should cover:

  • kosa8 and its config table: api_key, base_url, region and image;
  • the size mapping: 2x4, 4x8, 8x16 and 16x32, with the smallest that covers the request chosen;
  • the egress rules: up to 256 hosts, *. wildcards and IPv4 entries, applied at create;
  • that it's a paid service with no free tier.

The provider's own README.md has all of this.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The follow-up appears safe to merge; the earlier file-loading issue is fixed.

Summary

Adds kosa8 as a built-in cloud sandbox provider with Docker-capable VMs. The follow-up fixes file loading when an organization's network rules block a download host.

  • Kosa8 runs agent and environment sandboxes in Docker-enabled microVMs.

The previous finding is addressed. No new actionable issues were found in the follow-up changes.

Reviews (5) · Last reviewed commit: "fix(sandbox): a kosa8 sandbox pushes a f..." · Reviewed by Greptile

drvt69talati and others added 2 commits November 17, 2026 16:42
Adds kosa8 as a built-in VM sandbox provider, `kosa8`. It needs no extra:
it drives kosa8 Cloud's REST API with httpx. Each sandbox is a microVM
booted with docker: true from kosa8's universal Ubuntu 24.04 image, so
agent-env's docker-in-VM flows run unchanged; exposed ports are public
previews, egress allow lists are enforced on the host, and get_sandbox
restores both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The allow list now goes with the create, so kosa8 enforces it before the create answers and the VM never runs more
open than asked; a create kosa8 refuses for its allow list (an egress error code, or 501) is a policy it can't
enforce, so a fallback chain moves on. The PUT after boot, and the API call behind it, are gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale requested a review from a team as a code owner November 18, 2026 00:47
kosa8 compiles an org's deny list into `block:…`, or `;deny:…` after an allow list, which a NetworkPolicy can't carry;
read as allow-all, it let the sandbox try to curl a signed URL kosa8's host blocks, failing the load instead of
pushing the bytes over exec. The sandbox now keeps the denied entries beside its policy, from the create and from a
reconnect, and downloads only from a host its policy allows and nothing denies.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit ea8e6f1 into main Nov 18, 2026
39 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/kosa8-sandbox-provider branch November 18, 2026 01:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(sandbox): kosa8 Cloud sandbox provider

2 participants