Run bots in Akeru Cloud sandboxes from the environment #437

Problem

An Akeru Bot environment cannot use Akeru Cloud as a bot workspace. A bot set to Akeru Cloud has nowhere to run its commands and file edits, so the hosted sandboxes from AKR-135 cannot be used from the app.

Goal

The environment has an Akeru Cloud workspace provider. A bot on Akeru Cloud runs commands and edits files directly against its hosted sandbox, using short-lived, scoped access that the environment refreshes safely.

• Idle bots stop their sandbox. Resuming the bot reconnects to it.
• Chat shows clear, typed errors for an environment that is not linked to Akeru Cloud, an account that is out of credits, and a cloud that is offline. Out of credits includes an Add credits action.
• Each account and link gets its own workspace pool, and unlinking or suspension invalidates cached access and private host details.

Acceptance criteria

• Lifecycle requests reuse the correlated cloud request channel
• Boat commands and filesystem access work through in-memory Boat sessions with safe access refresh
• Workspace identities are wired, and the workspace pool is isolated per account and link
• Suspension and unlink are handled, and private host details are invalidated
• Not linked, out of credits, and offline show typed chat errors
• The feature sits behind a runtime flag, with docs and a minor changeset
• Stale cloud browser endpoints are discarded
• On staging, a bot on Akeru Cloud runs commands and edits files in its sandbox during a real turn
• On staging, an idle bot stops its sandbox, and resuming reconnects to the same sandbox
• On staging, an out-of-credits account shows the message with Add credits

How to verify

Run the focused Akeru Cloud workspace tests on the branch. Then run the parent's integrated check on staging: link an isolated dev environment to the staging cloud, set a bot to Akeru Cloud, and run a real turn that runs a command and edits a file. Let the bot go idle, resume it, and confirm it reconnects. Drain the test account's credits and confirm the chat error offers Add credits.

Out of scope

• Cloud Worker changes in apps/cloud. Provisioning and credits belong to AKR-135.
• The Settings → Sandboxes redesign (AKR-134)

Context

Parent: AKR-133 (Run bots in hosted Akeru Cloud sandboxes). This issue is blocked by AKR-135 (provision Boat sandboxes and bill prepaid credits). Builds on the Akeru Cloud foundation in PR #364.

Commits: the environment work was first committed as 03c77edaf (feat(server): run bots in Akeru Cloud sandboxes) and d79dc2417 (fix(server): discard stale cloud browser endpoints), both Refs AKR-136. They now sit on the akeru-cloud/sandbox-integration branch as 77a946512 and 62d7c04e4, followed by 6ddc52f81 (fix(client-runtime): describe what each cloud sandbox can do). The branch is not pushed yet.

Results on 2026-10-06: 113 focused tests, touched-path lint, and typechecks for akeru-bot, @akeru/contracts, @akeru/web, and @akeru/client-runtime pass. Findings from an independent GPT-6.1 Sol review (Standard tier, medium reasoning) are fixed with gated regression tests.

Not checked: live Akeru Cloud and Boat sandboxes, and the clients. This slice used fakes and no dev servers. The parent's integration and staging verification remain. No push and no apps/cloud edits were made.

Created with Claude Opus 5.5 in Claude Code.