Grok, Muse, Cursor and Antigravity

Use an installed native CLI to work assigned Velocity issues in isolated task worktrees.

Enable the runtime

A workspace owner or administrator enables the runtime in Settings → Agents → Agent and executor configuration. Enable assignment or mention dispatch as needed. Assign an issue to that agent or mention it in an issue comment; unassigned Todo issues are not automatically claimed.

Install and sign in locally

Install the vendor’s headless agent CLI and sign in using its own instructions. Editor launchers alone do not provide worker execution.

RuntimeNative executableVendor instructions
Grok BuildgrokGrok CLI
Muse CodemuseMuse Code
Cursorcursor-agent or agentCursor CLI sign-in
Antigravityagy or antigravityAntigravity CLI

Velocity verifies the executable’s identity and compatible capabilities. For example, an agent command pointing to Grok is not a Cursor installation. A detected but signed-out or incompatible runtime remains unavailable for new work.

Configure a waiting worker on the website

Install the verified worker release linked in the worker installation guide, then run velocity-agent login, then velocity-agent run. You can focus on one approved workspace with --workspace ID_OR_SLUG. Account-wide consent is not required.

Open Agents → Local workers in your workspace. Expand your worker’s row for a short summary, then select Edit settings to open its settings dialog. Fix setup opens the relevant problem directly; View details opens the full read-only details. The same controls are in Settings → Agents → Workers.

In Setup, choose an execution method, team, linked repository/project and optional model/effort, then select Save and start. Delivery contains the host workflow; Profiles contains delivery preferences; Details shows versions and runtime checks. Claude Code, Codex, Grok Build, Muse Code, Cursor and Antigravity have local execution adapters. Each still needs a compatible installed CLI and its own authentication. If several runtimes are detected, select one. An unconfigured worker stays connected and waiting.

Native execution uses the runtime’s own sign-in. Sign in separately with codex loginor claude auth login; Velocity never signs you in automatically or uploads provider secrets. Anthropic API execution needs ANTHROPIC_API_KEY on the worker; supplying an API key for Claude Code selects its SDK execution path. Configured authentication is not proof of model access; catalog and execution checks still apply.

Explicit CLI flags override website values. Omitted flags preserve the selected provider and execution method. Fields marked CLI option show the explicit value and cannot be changed on the website. Remove the corresponding option when restarting to give the website control. Use --no-allow-delivery to keep commits local or --no-single-checkoutto require task worktrees. Shared workspace restrictions remain authoritative.

A save stays pending until the worker acknowledges the saved revision. Needs attention lists the reported setup problems. Open Fix setup to review the runtime’s reported cause and next action; detection or saved sign-in alone does not prove access or remaining quota. Idle workers apply updates on the next poll; active tasks keep their execution settings until they finish. An offline worker must reconnect before applying updates. Conflicting saves preserve your draft; Reload settings fetches the latest revision for review. Older workers display applied revision not reported until upgraded.

Link a new private checkout once with velocity-agent repo link. The website selects among declared links; private checkout paths and credentials stay on the machine. The machine owner can save executable workflow commands on the Delivery tab or use a private host workflow file. Commands execute on the worker, so keep secrets in its environment. Full delivery needs the required validation, deployment and acceptance adapters; delivery preferences alone cannot supply them. See the host workflow setup steps.

Each workspace has its own settings and heartbeat. The worker refreshes inventory every minute, heartbeats every 15 seconds and appears offline after 90 seconds without contact. Pause, Stop and configuration edits take effect between tasks. Missing sign-in, unsupported model/effort pairs, unavailable runtimes, disconnected servers and missing repository links leave work pending. Check the terminal, correct the selection or relink the checkout, and the worker retries automatically.

Choose native defaults or explicit overrides

Run velocity-agent run, open Agents → Local workers, and configure the detected execution method, team and repository. Keep Model and Effort at Native default unless you want a specific override. Your explicit CLI options take precedence over website preferences; protected workspace policy still applies. An unavailable explicit model is refused instead of replaced.

velocity-agent grok models
velocity-agent muse models
velocity-agent cursor models
velocity-agent antigravity models

velocity-agent run --workspace YOUR_WORKSPACE --team YOUR_TEAM --executor grok

Model commands inspect native metadata without starting inference. Native catalog availability does not guarantee account entitlement or remaining quota. Cursor and Antigravity use their native reasoning defaults when per-model effort compatibility is not advertised. When metadata cannot be read, the command names the missing prerequisite: no CLI on PATH, an incompatible --help, a signed-out or failing native command, or an unrecognized catalog format, together with the next step. It never prints paths or raw native output.

For installations outside PATH, set an absolute executable path using VELOCITY_GROK_BIN, VELOCITY_MUSE_BIN, VELOCITY_CURSOR_BIN or VELOCITY_ANTIGRAVITY_BIN. An explicit path remains authoritative if missing.

Host checks and delivery

The worker creates an owned task worktree, keeps the execution lease active and performs configured checks and delivery. Native runtime sign-in and billing stay with the vendor. Unreported usage or cost appears as unavailable. These additional runtimes support local issue work; interactive resume, steering and hosted execution are not advertised for them.

Worker 0.5.39 reports the selected delivery stop and its source in normal startup logs. In the worker dialog, open Details → Selected delivery stop. A workflow can select local work, a pull request, merge, or deployment. The reported selection is checked against each issue’s requirements, enabled saved profiles and workspace limits before delivery; it is not confirmation that a specific run is authorized.

Antigravity loads a temporary run-scoped MCP entry in the task worktree. The worker restores the original configuration before host delivery. If recovery cannot safely preserve local edits, delivery waits and the private recovery journal is retained on the host.

Delivery authorization and recovered runs

Worker 0.5.36 names the issue and run when delivery is waiting and explains the current restriction. Allow delivery does not override a shared local-only policy, integration approval requirements, the connection that owns the attempt, or a human change to issue ownership or workflow. Review the specific setting named in the message rather than repeatedly enabling delivery.

Temporary restrictions are checked again after 30 seconds; unchanged waiting messages repeat at most every five minutes. An already closed issue or changed source, workflow or execution stops its original local continuation. The branch and worktree are preserved and the server’s original outcome is unchanged. If delivery finished elsewhere, open the original run’s delivery links. Restart an existing worker after installing an update to load its new code.

Minimum worker versions

Workspace owners and admins can set a minimum in Settings → Agents → Workers. Platform administrators set the system minimum in Admin → System. The stronger minimum applies. Both start unset, so existing installations remain eligible until an administrator configures a floor.

Preview the affected machines before applying a change. Enforcement is immediate for new tasks and delivery attempts; active attempts can finish safely, while expired or released leases require the current minimum before resuming. Policies require worker 0.5.27 or later to identify the version on every claim request. Earlier workers and unknown versions need an update whenever a minimum is configured. A version reported by another machine on the same account cannot authorize an old worker’s request.

Agents shows restricted workers and their actual reported versions, platform floor and workspace floor. Inbox records policy changes and deduplicated cutoff notices for workspace owners/admins and machine owners. Platform increases are announced even when a workspace’s higher minimum keeps its effective requirement unchanged. Credentials remain on the host; update the installed package and restart the worker to activate the new version.

When website settings are saved but a worker is waiting

Website settings save the required stop and checks. The worker also needs the corresponding validation, deployment and acceptance commands loaded on its machine. A deployment requirement with no host adapters keeps the issue queued; signing in again does not install those commands.

On Agents → Local workers, select Fix setup for a workflow problem, or expand the worker’s summary and select Edit settings → Delivery. In the dialog, open Deployment workflow and enable Configure workflow commands from this website. Only the machine owner can edit these executable commands. Choose the Default delivery stop, review Validation commands and configure Deployment and acceptance, then select Save and start.

The worker suggests validation scripts from the selected app’s package.json. Review the suggestions and add any checks required by the issue or profile. Use Name :: executable arguments for each validation line, with the exact required check names. Commands run in the task checkout without an implicit shell; use project scripts for pipelines. If no script is found, add a suitable command or an authorized validation waiver.

Choose Vercel for the built-in path. The worker retrieves the linked project and team IDs and production domains from the selected checkout’s .vercel/project.json and its local Vercel sign-in. Missing values in a new workflow can be filled automatically. Under Retrieve from Vercel, select Use discovered settings to copy the current details into your draft; choose a production domain first when several are available. If discovery is unavailable, follow its reported action or enter the IDs and production URL manually.

Review the suggested HTTP acceptance path, optional required response text and Vercel configuration path. A conventional health route is preferred; otherwise the default checks the home page. Stable response text is suggested only when it can be inferred; otherwise the default requires HTTP 200. These are editable suggestions, not proof that your application works. Saved values and your edits are preserved.

Install Vercel CLI and run vercel login on the host, or set VERCEL_TOKEN there. No provider credential is saved in Velocity. If the checkout is not linked, run vercel link there first. Save a changed repository selection before waiting for fresh discovery. The worker deploys a clean checkout of the merged commit, waits for Ready, checks that production has not changed during the build, promotes the project and verifies the same artifact around the HTTP acceptance check. An already Ready production artifact for that exact source can be reused. A known deployed descendant is never replaced by its older ancestor.

Vercel HTTP acceptance requires HTTP 200 and, when enabled, your chosen response text, in addition to the project, source, Ready and production-alias checks. Choose Custom commands or validation only for existing scripts, browser tests or another provider; use explicit deployment targets for a workflow spanning multiple projects. Commands execute from the installed worker, so a different velocity-agent earlier on PATH cannot replace the built-in verifier. The optional Vercel configuration path is relative to the repository root. The preset does not create projects or domains, change provider credentials or infer acceptance from issue completion.

Saved and applied revisions are separate. The worker acknowledges the loaded checks and deployment/acceptance capabilities before claiming its next task. Active attempts retain their pinned commands; changing a workflow does not replace an existing delivery’s evidence. Older workers show an upgrade message. Worker version is reported separately from the native Codex or Claude Code version.

Open Command inputs and required receipts for the deployment contract below. Use real release and acceptance scripts that verify the artifact and source SHA; a successful generic deploy command alone does not verify delivery. Credentials and provider sign-in stay on the host; never put tokens into website commands.

A private --workflow /absolute/path/workflow.json remains supported and takes precedence over website commands. Keep that file private (chmod 600); host-file changes require a restart. Explicit CLI delivery options also retain precedence, and protected policy always applies. Only the machine owner can change executable website commands, through their signed-in browser; issue text and managed executions cannot supply them.

Saved delivery profiles

Worker 0.5.24 adds saved native delivery profiles. Personal preferences belong to the connected worker’s signed-in account in the selected workspace.

Open Settings → Agents → Delivery defaults & overrides. Stable profiles are codex, claudeCode and anthropic. Codex and Claude Code support native delivery; Claude API does not support the native Git/CI/deployment adapters. Capabilities follow the installed worker release; there is no separate platform-admin delivery-defaults system.

Owners and admins set shared defaults and protected limits: the furthest permitted stop, required validation, deployment verification and named host checks. Members save only their own preferences and cannot authorize merge or deployment. Empty personal fields inherit shared defaults; clearing all personal fields restores inheritance. Model and effort choices remain separate.

Choose local implementation, tested PR handoff, merge after CI/review, or end-to-end deployment/release and verified Done. Host validation and deployment verification can be required individually. Commit/push, PR, exact-head CI/reviews, merge and verified closure have stage dependencies; a preference cannot disable a repository gate. Local and PR handoffs keep the issue unfinished.

To enable saved preferences once, add "profilePreferences": true beside "version": 1 in the private --workflow file, or enable inheritance in the website workflow editor. Keep credentials on the host. Assignments can then follow the saved authorized end-to-end stop without repeating --allow-delivery. Existing files remain explicit and existing local-only restrictions stay in effect until the operator opts in. An explicit --no-allow-delivery remains local-only; choose a workflow or a delivery flag, not both.

Protected system, workspace/provider and shared-profile constraints always apply. Within those limits: explicit CLI → per-issue settings/cues → personal preferences → shared defaults → host fallback. Host-required checks and deployment verification remain floors. A profile never supplies credentials, executable commands, repository authorization or GitHub access.

The worker fetches a next-attempt preview at connection, pins shared/personal revisions with the issue choice before claim, and revalidates relevant writes and delivery boundaries. Workers and run details show the selected stop, sources, revisions, unsupported stages and missing checks/adapters. GitHub/CI/release access is verified at the actual boundary. Any profile edit stops active delivery at its next authorization check; start a new attempt to adopt it. Retrying an existing prepared delivery preserves its original evidence. Older workers cannot ignore a configured shared profile and need upgrading. Settings show recent shared and caller-owned history.

MCP get_agent_delivery_profile takes profileId. update_agent_delivery_profile also takes scope (workspace or personal), expectedRevision, expectedSharedRevision and settings. Both revisions must match; conflicts require reload and review. Personal settings accept mode, validationRequired, deploymentRequired and requiredChecks. Shared settings wrap these in defaults and add limits with maxMode, validationRequired, deploymentRequired and requiredChecks. No user/workspace selector can replace authenticated ownership; managed executions cannot change their own profiles.

GraphQL exposes agentDeliveryProfile(workspaceId, profileId) and updateAgentDeliveryProfile(workspaceId, input). The management CLI provides velocity agents delivery-profile --profile-id codex and velocity agents update-delivery-profile --input @profile.json; select the authorized workspace normally. Run details expose the frozen workflowSelection separately from delivery progress.

Per-issue workflow choices

In issue details, open Agent workflow before choosing an assignee. Set the stop point and named host checks, or clear overrides to restore inheritance. The last attempt shows its pinned revision, resolved policy and value sources.

For a worker configured with --workflow, add "issueOverrides": true at the top level of the private configuration file to let issue choices replace its defaults. Without this operator opt-in, the explicit CLI workflow takes precedence. Required host checks, workspace policy and role restrictions still apply. Issues select check names; they cannot supply executable commands.

A user can add a top-level paragraph in an issue or a new comment containing one of these exact directives:

/agent-workflow implement and test only
/agent-workflow open a PR but do not merge
/agent-workflow complete delivery and mark Done after verification

Use one directive at a time, or /agent-workflow inherit. The first two resolve to local and PR handoffs with validation required. Complete delivery requests merge, deployment acceptance and Done; only owners/admins can request it and a deployment adapter is required. Structured issue controls take precedence over cues. Quotes, code blocks, attachments, agent comments, imports and API text cannot authorize delivery. Ambiguous directives block new work until resolved in the controls.

Queued work reads the latest revision. Running work keeps its pinned attempt: any workflow edit stops it at the next host authorization boundary before further delivery writes, and requires a new attempt. Once delivery is prepared, reassign the agent to start a new run after an edit; an ordinary retry retains its original evidence. Recover saved changes with velocity-agent repo tasks. Editing or deleting the latest recorded directive revokes it; newer directives are preserved. The issue controls also clear recorded directives. This is delivery steering, not arbitrary live model instruction updates.

Finish a delivery workflow

Worker 0.5.12 can validate changes, commit and link them, open a PR, wait for GitHub checks and required reviews, merge, and close the issue after any required deployment. Coding and delivery have separate recorded states in Agents → the run.

Use the website workflow editor, or --workflow /absolute/path/workflow.json with a private operator file (chmod 600). Existing commands keep their local-only behavior; --allow-delivery remains a PR-only handoff. Choose one delivery option.

{
  "version": 1,
  "policy": {
    "mode": "merge",
    "validationRequired": true,
    "deploymentRequired": false,
    "maxRepairAttempts": 1
  },
  "checks": [
    {
      "name": "Repository checks",
      "argv": [
        "pnpm",
        "test"
      ]
    }
  ]
}

Replace the check with the appropriate commands for your repository. Arguments execute directly, without a shell. Supply credentials through your environment, never command arguments. For a low-impact change that needs no checks, set validationRequired: false and provide a meaningful skipValidationReason; the reason is recorded.

The stop modes are local, pr, merge and deploy. Local and PR modes leave an explicit handoff and keep the issue unfinished. Merge/deploy require a workspace owner or administrator. Current permissions, repository mapping, approval settings, emergency stop and delivery limits still apply. The CLI file cannot override a protected workspace limit.

For a product that requires release or deployment, choose deploy and deploymentRequired: true. Configure deployment.deploy and deployment.verify as argument arrays for your existing release and acceptance scripts. Each receives VELOCITY_DELIVERY_SOURCE_SHA. Deploy must print one JSON receipt with sourceSha, artifactId and an HTTPS url without credentials, query parameters or a fragment. Verify receives that receipt on stdin, checks the actual artifact and meaningful acceptance behavior, and prints the same identity plus acceptancePassed: true. Logs go to stderr. Failure or a different source/artifact keeps the issue unfinished. Merge-only mode does not claim a production release.

Use Stop delivery on the run page to stop an unfinished workflow, including after coding has completed; the runner owner or a workspace administrator can do this. CI waits release the coding session. Keep the same runner polling, or restart it with the same account, workspace, repository links and workflow file. A changed workflow does not upgrade a pinned job. Confirm a crashed process is stopped before using velocity-agent repo recover for its owned checkout lock; dirty work and branches are preserved.

If delivery continues elsewhere, open Delivery continuations on the original run and link the specific successor run, pull request or follow-up contact. Successor runs link back to their origins. A completed coding turn or an issue marked Done does not verify deployment; the original execution result remains visible alongside its continuation.

For a Vercel deployment completed outside the run, an owner or administrator can run the preset’s vercel-verify command with --external-receipt, then submit its successful receipt using velocity-agent workflow record-delivery --workspace WORKSPACE --run RUN_ID --pr PR_URL --receipt FILE. The server confirms the exact merged source, successful checks, required reviews and origin backlink. Artifact links identify the immutable deployment. Recording acceptance retains the original run result and does not close the issue.

When no new source changes are needed

Worker 0.5.40 can reuse a same-issue, exact-source accepted delivery after rechecking the merged PR’s checks, required reviews and pinned host acceptance verifier. No empty commit, duplicate PR or deployment is needed. Without sufficient proof, the run stays open with DELIVERY_NO_CHANGES.

Open Review existing work on the run, select its actual earlier delivery or linked PR, and run the displayed velocity-agent workflow verify-existing command from the linked repository on the original worker host. Add the original private --workflow file if one was used; its command digest must match. The command locks the preserved worktree, reruns pinned validation and only the acceptance verifier, then records fresh evidence. The original requester must explicitly accept in the browser within 15 minutes. Completion adds one comment and marks the issue Done together, preserving the coding outcome and earlier handoff with links to the actual delivery. Current permissions, requirements, ownership, policy and minimum worker versions still apply. Local and PR handoffs retain their selected stop.

Relevant validation and CI failures can queue up to maxRepairAttempts additional native turns (0–3, default 0). Repairs retain the original runtime deadline and use normal claim/concurrency checks. Exhausted repairs become Blocked with the reason and preserved work. A provider outage waits for a later poll. No request bypasses GitHub branch protection or required reviews.

An approval does not clear outstanding review findings. Delivery rechecks current conversations and standing change requests before merging, even when a reviewer check is neutral or skipped. Address the finding and resolve its conversation on GitHub; the worker rechecks the same PR. Unreadable review evidence waits for a complete read.

To require an automated reviewer such as Cursor Bugbot, list it under Required reviewers in the GitHub integration settings as app-slug/Check name, for example cursor/Cursor Bugbot. Delivery then waits, as Review required, until that app reports its own check on the pull request's current commit. A reviewer that never started or ran only on an earlier commit is never counted as skipped, and local-only validation does not waive it. A neutral or skipped result is accepted once its annotations are read and none is a warning or failure.

Done requires recorded validation or a skip reason, exact-commit CI/review evidence, a confirmed merge, any required verified deployment, and one completion comment committed together with the issue transition. Per-profile web configuration is tracked separately. Authorized per-issue choices can refine the operator file when it opts in with issueOverrides.