Skip to content

api, server: require Task spec.profile to name an image; drop the default image - #647

Merged
rakyll merged 2 commits into
mainfrom
image
Nov 20, 2026
Merged

rakyll merged 2 commits into
mainfrom
image

Conversation

@rakyll

@rakyll rakyll commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

ax-server used to fall back to a server-wide default task image when a Task's profile set neither image nor ateTemplate.name. That default, v1alpha1.DefaultTaskImage, had no @sha256 digest and pointed at a private repo, so Substrate rejected it unless an operator overrode it with --default-task-image / AX_DEFAULT_TASK_IMAGE. Remove the default: every task now runs an image it names, directly or through its Workspace.

API

  • A set profile, on a Task or a Workspace, must name image or ateTemplate.name (validateProfile).
  • A Task that omits spec.profile still inherits its bound Workspace's spec.profile, whole and never field-merged. ValidateTask rejects a Task that has no profile and binds no Workspace. CreateTask rejects one whose Workspace has no profile to inherit.
  • A Workspace with setup steps must set spec.profile, because setup runs in a sandbox started from it (ValidateWorkspace). This applies whether or not pre-warming is enabled.
  • Update the task.proto and workspace.proto comments and docs/manifests.md.

Server and controller

  • Remove v1alpha1.DefaultTaskImage, the ax-server --default-task-image flag, AX_DEFAULT_TASK_IMAGE, and the defaultTaskImage plumbing through TaskReconciler, WorkspaceManager, ResolveProfileTemplate, and substrate.BuildActorTemplate.
  • Tasks stored before this change that resolve to no image now fail with TemplateCreationFailed. They no longer run a default image.

Install and release

  • Remove --default-task-image from ax install / ax local start, and remove AX_DEFAULT_TASK_IMAGE from deploy/ax-server.yaml, the deploy renderer, and axdeploy.
  • Rename the release output AX_DEFAULT_TASK_IMAGE to AX_TASK_RUNNER_IMAGE. make images now prints the digest-pinned ax-task-runner ref to use as spec.profile.image.

Examples, docs, and tests

  • Give Workspaces with setup steps a profile: the README example, examples/claude-code/task.yaml, the E2E manifests, and the unit tests. In the README and claude-code examples, the Task now inherits the Workspace's profile.
  • Update README, docs, demo.sh, the E2E harness ({{taskImage}} expands to $AX_E2E_TASK_IMAGE), and skills/substrate/SKILL.md to match.

…ault task image

ax-server used to fall back to a server-wide default task image when a
Task's profile set neither image nor ateTemplate.name. That default,
v1alpha1.DefaultTaskImage, had no @sha256 digest and pointed at a
private repo, so Substrate rejected it unless an operator overrode it
with --default-task-image / AX_DEFAULT_TASK_IMAGE. Remove the default
and require every task to say what it runs.

API
- Task.spec.profile is now required and must set image or
  ateTemplate.name (apivalidation.ValidateTask).
- When pre-warming is enabled, a Workspace with a profile or setup
  steps must set spec.profile.image or ateTemplate.name
  (ValidateWorkspacePrewarm).
- Workspace.spec.profile is no longer a fallback profile for Tasks. It
  is only used to pre-warm the workspace snapshot. Update the
  task.proto and workspace.proto comments and docs/manifests.md.

Server and controller
- Remove v1alpha1.DefaultTaskImage, the ax-server --default-task-image
  flag, AX_DEFAULT_TASK_IMAGE, and the defaultTaskImage plumbing
  through TaskReconciler, WorkspaceManager, ResolveProfileTemplate, and
  substrate.BuildActorTemplate.
- Tasks stored before this change that resolve to no image now fail
  with TemplateCreationFailed. They no longer run a default image.

Install and release
- Remove --default-task-image from ax install / ax local start, and
  remove AX_DEFAULT_TASK_IMAGE from deploy/ax-server.yaml, the deploy
  renderer, and axdeploy.
- Rename the release output AX_DEFAULT_TASK_IMAGE to
  AX_TASK_RUNNER_IMAGE. `make images` now prints the digest-pinned
  ax-task-runner ref to use as spec.profile.image.
- Update README, docs, demo.sh, the E2E harness, and manifests to
  match.

@aojea aojea left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

I assume that at this point we do not worry much about compatibility based on the v1alpha1 group so changes are mostly mechanical s/default_image/profile/ with validation in place to ensure the image is set in the profile

Comment thread internal/apivalidation/task.go Resolved
Comment thread internal/apivalidation/common.go Resolved
Comment thread internal/apivalidation/workspace.go Resolved
Comment thread internal/server/workspace.go Resolved
Comment thread pkg/apis/v1alpha1/task.proto Resolved

@mayawang mayawang left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

LGTM on dropping the default image, an undigested private default was never going to work. Yuchen's inheritance question is the one to settle before we tag, since it's the v1alpha1 contract. Heads up that hack/hero-demo/workspace.yaml has setup but no profile, so it'll fail ValidateWorkspacePrewarm once prewarm is on

Resolve conflicts with main (ensureProfileTemplate refactor, removal of
firstUnimplementedWorkspaceField, Studio docs) and address review:

- Keep inheritance: a Task that omits spec.profile uses its bound
  Workspace's profile. ValidateTask requires spec.profile only when the
  Task binds no Workspace; CreateTask rejects a Task whose Workspace has
  no profile to inherit.
- Fold the image check into validateProfile: a set profile must name
  image or ateTemplate.name.
- Replace ValidateWorkspacePrewarm with a check in ValidateWorkspace:
  a Workspace with setup steps must set a profile, whether or not
  pre-warming is enabled.
- Give the README, claude-code example, E2E and unit-test Workspaces with
  setup steps a profile.
@rakyll

rakyll commented Nov 20, 2026

Copy link
Copy Markdown
Member Author

PTAL

@rakyll
rakyll merged commit 465cbeb into main Nov 20, 2026
12 checks passed
@rakyll
rakyll deleted the image branch November 20, 2026 19:09
@rakyll rakyll mentioned this pull request Nov 21, 2026
4 of 6 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants