Feat/opensandbox support

[Aman-goel-04]

Summary

Adds OpenSandbox as a supported sandbox provider in TrueForge.

This includes backend/provider support, API and schema changes, generated SDK support, UI configuration, provider-specific startup timeouts, and MCP Code Mode tool discovery.

Closes#371

Changes

• Added OpenSandboxProvider to trueforge-core.
• Added OpenSandbox sandbox creation, execution, endpoint handling, snapshot handling, lifecycle handling, and cleanup.
• Added OpenSandbox configuration fields:
  • domain
  • protocol
  • exec_timeout_ms
  • auth.api_key
• Added OpenSandbox to the sandbox provider schema, catalog, API routes, provider dispatch, and persistence flow.
• Preserved existing Daytona behavior and configuration semantics.
• Preserved API-key redaction/update behavior:
  • Supplying a new key replaces the stored key.
  • Omitting the key preserves the existing key on update.
• Added OpenSandbox-specific UI configuration for:
  • API key
  • API domain
  • HTTP/HTTPS protocol
  • Execution timeout
• Updated the UI adapter so OpenSandbox domain and protocol are preserved through:
  UI form → UI adapter → SDK → API manifest
• Added a provider-specific OpenSandbox build timeout while preserving Daytona's existing timeout.
• Fixed Code Mode MCP discovery to use the MCP protocol-level tools/list operation instead of attempting to call a remote tool named list_tools.
• Preserved Streamable HTTP MCP session handling.
• Added the required local Docker host binding for the smoke-test healthcheck.
• Regenerated the OpenAPI documents and TypeScript SDK using pnpm sdk:generate.
• Added and updated unit, contract, API, schema, UI, and provider-utils tests.

Compatibility note

The current assistant-ui-runtime contract is still Daytona/lifecycle-shaped.

OpenSandbox therefore uses the maintainer-approved 0 compatibility values for the lifecycle fields while retaining its actual domain, protocol, and execution-timeout configuration.

Refactoring the runtime contract is outside the scope of this PR.

How was this tested?

Automated checks

The following pass locally:

• pnpm build
• pnpm test
• pnpm typecheck
• pnpm lint:ci
• pnpm format:check
• pnpm pack:dry
• git diff --check
• pnpm smoke

Test coverage includes:

• OpenSandbox provider unit tests
• Sandbox provider contract tests
• API and schema validation tests
• Provider dispatch and persistence tests
• UI adapter and configuration-form tests
• Generated SDK tests
• Existing Daytona tests

Manual OpenSandbox verification

Using a local OpenSandbox server backed by Docker:

• Health endpoint returned 200.
• TrueForge displayed OpenSandbox as connected.
• Sandbox creation succeeded.
• echo 1 executed successfully and returned exactly 1.
• A file containing print(2 + 3) was created and executed, returning exactly 5.
• File creation, reading, upload, and download worked.
• Sandbox state was preserved across turns.
• OpenSandbox domain and protocol were retained through provider updates.
• Startup latency exceeding three seconds was handled by the provider-specific timeout.
• OpenSandbox logs confirmed successful sandbox creation, endpoint retrieval, and command execution.

MCP / Code Mode verification

Against the configured trueforge-test-mcp server:

• MCP initialization succeeded.

• Streamable HTTP session handling succeeded.

• mcp-client list-tools trueforge-test-mcp performed the actual MCP tools/list operation and returned:

  hello

• mcp-client call-tool trueforge-test-mcp hello successfully invoked the discovered tool and returned:

  Hello, World!

The hello tool was preconfigured on the test MCP server; this change verifies that TrueForge discovers it through the MCP protocol's tools/list operation rather than hardcoding the tool name.

Checklist

• I have read the contributing guidelines.
• pnpm build, pnpm test, pnpm typecheck, pnpm lint:ci, and pnpm format:check pass locally.
• Tests added/updated where appropriate.
• Generated SDK/OpenAPI files were generated with pnpm sdk:generate and were not hand-edited.
• OpenAPI documents remain synchronized.
• No additional .env.example changes were required.
• Temporary diagnostic scripts and local-only files are not included.

Follow-up design consideration

The current sandbox-provider update route performs provider build/snapshot I/O inside the existing database transaction. This preserves the current locking and atomic persistence behavior, but OpenSandbox image creation and snapshotting can take considerably longer than the Daytona path.

Moving this remote I/O outside the transaction should be considered separately, together with explicit handling for:

• concurrent provider updates,
• concurrent OpenSandbox snapshot creation,
• stale build results,
• transaction retries,
• cleanup after a failed or interrupted build.

This PR keeps the existing transaction structure intentionally to avoid changing those concurrency semantics without a maintainer-approved design.

---

Note

Medium Risk
Introduces a new remote code-execution path with API keys and tenant-scoped sandbox access; build/snapshot behavior and multi-replica races are documented but not fully coordinated yet.

Overview
Adds OpenSandbox alongside Daytona as a tenant-configurable sandbox backend, wired end-to-end from API/schemas through runtime dispatch, generated SDK, catalog, and settings UI.

OpenAPI and persistence now model SandboxProviderManifest and catalog presets as a discriminated union (daytona vs opensandbox), including OpenSandboxProviderAuth, domain, protocol, and generic 422 copy when a provider rejects an API key. The Fern-generated SDK and docs OpenAPI files are regenerated accordingly.

Runtime introduces OpenSandboxProvider in trueforge-core (golden snapshot “build”, tenant metadata checks, exec/files, Code Mode NATS transport with secureAccess: false) and routes all construction through toSandboxProvider. PUT sandbox settings uses a longer build timeout for OpenSandbox than Daytona; auth errors from either provider map to the same 422 response.

UI exposes OpenSandbox-specific fields (API domain, HTTP/HTTPS, exec timeout) while omitting Daytona-only lifecycle intervals; the catalog adapter round-trips domain/protocol and preserves provider type on update.

Code Mode MCP discovery is corrected: sandbox mcp_client / mcp-client gains list-tools, agent reminders require MCP tools/list via list_tools (not call_tool), and the shared provider contract test no longer assumes sandboxId equals the exec cwd for opaque-id backends.

Minor: docker-compose sets HOST: 0.0.0.0 so container healthchecks can reach the server.

^{Reviewed by Cursor Bugbot for commit a29077c. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: a29077c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@truefoundry/trueforge-sdk	Patch
@truefoundry/trueforge	Minor
@truefoundry/trueforge-core	Minor
@truefoundry/trueforge-ui	Minor
frontend	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cursor]

Build I/O runs inside transaction

Medium Severity

The OpenSandbox buildImage path awaits remote sandbox creation and snapshotting inside withTransaction, holding the DB lock for up to 30s. Remote I/O must finish before the transaction; callbacks may only do local DB work.

^{Triggered by project rule: @truefoundry/trueforge review rules}

^{Reviewed by Cursor Bugbot for commit d78129c. Configure here.}

[Aman-goel-04]

I’m leaving the transaction structure unchanged in this PR because moving the build outside the transaction requires redesigning the locking/concurrency behavior for concurrent provider updates. The current implementation preserves the existing atomic update semantics.

I’ve documented this as a follow-up design item for maintainer review.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 055643a. Configure here.}