Skip to content

feat: add organization default Agent Profiles with Sandbox Spec references (OHE-4186) - #1448

Open
rajshah4 wants to merge 6 commits into
mainfrom
codex/ohe-4186-org-default-profile
Open

rajshah4 wants to merge 6 commits into
mainfrom
codex/ohe-4186-org-default-profile

Conversation

@rajshah4

@rajshah4 rajshah4 commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

HUMAN:

  • A human has tested these changes.

AGENT:

Implemented with OpenHands using Bedrock Opus. Coordinator review, integration testing and small client/docs follow-through were agent-operated.

SDK dependency: Enterprise main now pins SDK 1.63.1 in the app and Mypy hook. The local #1448 candidate integrates those pins and passes Mypy. GitHub CI for that candidate and packaged Compose acceptance are still pending. SDK bump · Mypy alignment

Dependency and merge order

SDK PR #6948 added the optional Sandbox Spec reference to Agent Profiles. Revalidate native Compose acceptance against the released dependencies before merging.

Why

Organizations that maintain a custom tools image need a shared default environment. An owner or admin can designate a shared Agent Profile as the organization default. The profile can reference an existing Sandbox Spec, and members can select another profile or keep a personal Sandbox Spec preference.

An Agent Profile stores an optional sandbox.spec_id that refers to an existing Sandbox Spec. The provider defines the environment before launch, including the image tag and any supported CPU and memory settings. Enterprise resolves the reference when a new sandbox is needed. This draft uses the deployment's existing image-backed Sandbox Specs.

This follows the smaller profile-based proposal.

Summary

  • Expose set/clear organization-default actions using the existing profile pointer, with owner/admin permissions, scope checks, safe deletion and a matching UI badge.
  • Let profile editors choose an existing Sandbox Spec offered by the deployment.
  • Carry the spec reference in the resolved profile snapshot and display the inherited choice separately from the saved personal preference.

Sandbox selection precedence

Enterprise selects the agent profile in this order.

  1. Profile ID (agent_profile_id) supplied in the conversation start API request. This one-time override applies only to that conversation. The member's saved profile selection stays the same.
  2. Member's selected agent profile.
  3. Organization default agent profile.

When provisioning a new sandbox, Enterprise uses an explicit spec if the launch path supplies one, then a valid saved personal preference, then the resolved Agent Profile’s spec, then the deployment default. A profile with no spec leaves selection to the other tiers. Existing sandboxes keep their environment.

The named Sandbox Spec catalog and organization allowlist are follow-up integration work with #948. In that integration, the launcher checks each candidate spec ID against the effective organization’s policy. A saved profile cannot launch a spec the organization has removed. PRD-197 tracks what the user should see when that happens.

Before enabling named-spec policy for an organization with saved profiles, account for existing image-backed IDs. The policy checks exact named spec IDs. If a profile still stores an image reference, the administrator needs to choose the intended allowed spec or explicitly map it during rollout. Multiple specs can share an image, so the old image reference alone may be ambiguous.

Issue Number

OHE-4186

How to Test

The historical validation below used an isolated environment with the candidate SDK. On the updated standalone candidate with the released SDK 1.63.1, five PostgreSQL-backed suites passed 764 tests with one skip. The worker's frontend checks passed 40 tests with one skip. Mypy, Ruff, and the package and version checks passed locally.

  1. Enable the existing Agent Profiles switch on a disposable self-hosted stack.
  2. As owner/admin, edit a shared OpenHands profile, select an advertised Sandbox Spec and set the profile as organization default.
  3. As a member with no personal selection, start a new conversation and check its actual sandbox image and recorded profile revision.
  4. Select another profile or a personal Default Sandbox Spec. Clear the personal preference and verify the inherited spec is shown without saving it as a preference.
  5. Select a profile with no Sandbox Spec, clear the organization default, rename or delete the default profile, and verify existing sandboxes retain their original environment.

Validation completed before rebasing onto Enterprise base b0d455745:

  • Main affected backend run: 855 passed, 1 skipped, using PostgreSQL and the candidate SDK wheel.
  • Final profile-route run: 115 passed, including a legacy organization ACP regression that failed before its new 422 guard.
  • Focused frontend: 57 passed, 1 skipped across the profile/settings suites. Typecheck, production build, lint and formatting passed.
  • Native packaged Compose acceptance: 20 checks with 10 actual sandbox starts using stock/custom images, plus profile provenance, precedence, permissions, organization isolation and cleanup.
  • Browser: 10 owner/member checks passed, including default set/clear, profile image save/restore, personal override/clear and profile selection/deactivation.

After rebasing onto b0d455745, 717 backend tests passed and 1 skipped, covering profiles, conversation creation, auth/secrets, integration resolver contexts and remote sandboxes. Against the updated frontend lockfile, 24 focused tests, typecheck and production build passed. A test-only union narrowing was added after typecheck identified the issue. The native Compose and browser results above were collected before this rebase.

The normal Mypy hook passed on the updated local candidate. GitHub CI and packaged Compose acceptance for that candidate remain pending.

Video/Screenshots

Synthetic local fixtures only:

Type

  • Bug fix
  • Feature
  • Refactor
  • Breaking change
  • Docs / chore

Notes

No database migration or organization image column is added. Organization defaults point to existing shared profiles. Automations retain existing profile selection and use the ordinary spec resolution path when provisioning a new sandbox. Parent inheritance, profile copying and GitOps management are out of scope.

This remains a draft pending GitHub CI and packaged Compose acceptance for the updated candidate.


Enterprise server image for this PR:

ghcr.io/openhands/enterprise-server:sha-d11de9d

rajshah4 and others added 3 commits November 17, 2026 15:20
…HE-4186)

Use the existing organization profile pointer and preserve personal overrides. Carry the selected profile image with its launch snapshot across sandbox backends. No migration, parent inheritance, copying, or per-automation image picker.

Local draft: validated with the candidate SDK wheel. The normal Mypy hook still targets the released SDK and remains a release/dependency alignment gate; it is explicitly skipped for this unpublished local commit.

Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: openhands <openhands@all-hands.dev>
@github-actions

Copy link
Copy Markdown

📁 PR Artifacts Notice

This PR contains a .pr/ directory with PR-specific documents. This directory will be automatically removed when the PR is approved.

For fork PRs: Manual removal is required before merging.

@github-actions github-actions Bot added the type: feat A new feature label Nov 18, 2026

Copy link
Copy Markdown
Member

Two follow-up concerns to make the sandbox profile contract explicit:

  1. Recursive / cross-provider spec resolution
    profile.sandbox.spec_id should be consumed by the outer sandbox-provisioning layer only. If the resolved profile/provenance is copied into the remote agent-server, the spec can be preserved as provenance, but the inner server should not re-interpret it unless it explicitly owns the same spec catalog. Otherwise a Cloud/Enterprise spec could be recursively or incorrectly resolved by a nested/local runtime.

  2. SDK resolution gap
    The SDK profile model can now store sandbox.spec_id, but current local SDK paths do not uniformly honor it: DockerWorkspace uses server_image, and the agent-server Docker runtime uses Config.conversation_image. If profile sandbox metadata is intended to be generally supported, SDK/local runtimes need a resolver/capability story; otherwise this should be documented as host-specific metadata, with unsupported specs rejected or visibly ignored rather than silently falling back.

This comment was created by an AI agent (OpenHands) on behalf of the user.

@rajshah4

Copy link
Copy Markdown
Member Author

Thanks, Rohit. The launcher that provisions the sandbox owns the sandbox.spec_id lookup. If an automation copies the profile to an agent server running in an existing sandbox, the field can travel with the profile as metadata and the server starts the conversation without resolving it. In Enterprise, we validate the ID against the deployment’s catalog on save and log a warning if a previously saved spec is later removed. #6974 tracks the local Docker example and a regression test for a copied profile whose spec ID is unknown to the receiving server.

@rajshah4

Copy link
Copy Markdown
Member Author

On the second point, I’d keep sandbox.spec_id scoped to the launcher’s catalog. The profile carries the ID, and the launcher decides what that ID means in its environment. If a sandbox spec needs CPU, RAM, or other provider-specific settings later, those can live in the catalog entry. For now, Enterprise uses the ID to select an image, and the local Docker example can resolve it against its own image map.

@jlav jlav left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm onboard with this feature at a high level, but I just need to make sure this is well understood by all parties that are making sandbox changes:

We support several providers already, and plan to introduce more. Many providers require that the specifications for a sandbox environment are defined before the sandbox is actually created:

  • K8S Agent Sandbox has a warm pool, where the sandbox image, cpu, memory, and other environment details are configured.
  • E2B has Templates, which are similar to above.
  • Runtime API also has a warm pool

Many other providers follow the same pattern.

We must separate the environment definition from Sandbox creation to remain flexible as to what providers we can support.

I'm raising this concern now because I see that OpenHands/software-agent-sdk#6948 has a sandbox object with a spec_id to "[leave] room for additional typed sandbox settings, such as CPU and memory requests".

We should absolutely not begin building features out under the assumption that we can modify CPU, memory, and many other details of the runtime environment on demand like that because, largely, we cannot do that across sandbox providers. I know we're not doing that right now, but I want to call it out so we're aligned.

Last, we're inconsistently calling sandbox specs "images". Since runtime API has a runtime config, agent sandbox has a warm pool config, and e2b has a template, we should just centralize on the term "Sandbox Spec", or something generic like "Sandbox Environment". Image is too specific, since most of the specs determine much more than just the image.

#1448

# Conflicts:
#	frontend/src/i18n/declaration.ts
#	frontend/src/i18n/translation.json
#	frontend/src/routes/app-settings.tsx
…rors/docs

Reviewer feedback (review 5994210033 on #1448): the chosen Sandbox Spec
controls image/resources via the provider's preconfigured definition;
launches select a spec, not an image, so user-facing copy, comments,
and error text should say 'sandbox spec' rather than 'image'. No API
field renames, no SDK resource overrides, no profile schema change.
Preserves {{image}} interpolation key and actual image diagnostics.
@rajshah4 rajshah4 changed the title feat: add organization default agent profiles with sandbox images (OHE-4186) feat: add organization default Agent Profiles with Sandbox Spec references (OHE-4186) Nov 20, 2026
@rajshah4

Copy link
Copy Markdown
Member Author

Thanks, Joe. Your feedback helped clarify where the sandbox configuration belongs. I updated the PR title, description, and English settings UI to use Sandbox Spec. The Agent Profile stores sandbox.spec_id, and Enterprise resolves it when it needs a new sandbox. The provider defines the image and any supported CPU and memory settings ahead of launch.

This PR uses the existing image-backed catalog. The same field can reference a named spec when #948 lands.

@github-actions

Copy link
Copy Markdown

Coverage report

Click to see where and how coverage changed

FileStatementsMissingCoverageCoverage
(new stmts)
Lines missing
  integrations
  resolver_context.py 171
  openhands/app_server/app_conversation
  live_status_app_conversation_service.py
  openhands/app_server/sandbox
  docker_sandbox_service.py
  e2b_sandbox_service.py
  k8s_agent_sandbox_service.py
  process_sandbox_service.py
  sandbox_service.py
  sandbox_spec_models.py
  sandbox_spec_service.py
  openhands/app_server/settings
  settings_models.py
  openhands/app_server/user
  auth_user_context.py
  user_context.py
  server/routes
  agent_profiles.py 953
  storage
  saas_settings_store.py
Project Total  

This report was generated by python-coverage-comment-action

@rajshah4
rajshah4 marked this pull request as ready for review November 20, 2026 17:58

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

type: feat A new feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants