Skip to content

Vibe Headless Mode Gotchas

Headless Vibe runs need an explicit execution contract. These notes were refreshed for Vibe 3.0.0 on 2026-10-19. Historical advice about approval defaults, retry counts, or a universal concurrency of three should not be treated as current guarantees.

Flags to know: approvals and saved sessions

Section titled “Flags to know: approvals and saved sessions”

The CLI flags were rechecked against Vibe 3.0.1 on 2026-10-21. The version-pinned implementation analysis below remains a 3.0.0 snapshot.

Terminal window
vibe --yolo
vibe --continue --yolo
vibe --resume SESSION_ID --yolo
vibe --continue --prompt "Continue the task" --time-limit 300 --max-turns 12

--yolo aliases --auto-approve. In headless mode, supply an explicit session ID for deterministic resumption; vibe --resume without an ID is an interactive picker. Add --output streaming for events and --output-dir /path/to/private-artifacts for retained evidence. Review partial files after a deadline before retrying or resuming. The 300-second example is a chosen limit, not a universal timeout.

Current 3.0.1 headless runs use the configured default agent; a tool that requires unanswered approval is denied. Explicit auto-approval is therefore different from merely passing -p. Administrator policy can disable it. Resumed sessions retain their saved agent, so a newly supplied --agent is not proof that the old profile changed. See the full flag table and official current behavior.

Current programmatic mode uses the configured default agent; unattended approval requests are denied. Specify the intended agent for fresh dispatcher sessions and verify the saved agent on resumed ones. Keep profile selection and explicit --auto-approve / --yolo separate. A profile called read-only is insufficient if an enabled shell can still write files.

Use an explicit tool allowlist. Enable only file-reading/search tools for reconnaissance. For an editing worker, approve the execution boundary first; auto-approve can execute arbitrary commands reachable through its tools. Review repository configuration, hooks, skills, and project instructions before granting --trust.

A separate Git worktree protects the source checkout from accidental edits and provides a clean diff. It does not prevent access to other directories, shared Git metadata, credentials, the network, or production services.

Run untrusted generated code under a separate unprivileged identity, filesystem and network isolation, and resource limits. Keep provider credentials, personal home directories, SSH agents, browser sessions, and deployment capabilities outside that environment. A tool denylist is not a substitute for these boundaries.

Use every applicable layer:

LimitWhat to enforce
Wall timeNative --time-limit plus a supervising process that terminates the worker’s process group and kills it after a short grace period
Turns--max-turns; also disable unneeded child agents so work cannot expand outside the dispatcher
Session tokens--max-tokens stops on reported cumulative prompt + completion usage, including repeated input; account for child/background calls separately
Response tokensModel max_output_tokens, such as 1,024; verify the resulting per-request inference cap
Spend--max-price as an estimate, with provider/account spending limits as the billing control
ResourcesRuntime memory, CPU, process, disk, and concurrency caps

Vibe 3.0’s CLI --max-tokens is a cumulative run budget. It is enforced client-side and is not sent as the app-server’s per-request max_tokens setting, so --max-tokens 60000 does not replace a model’s max_output_tokens = 1024. An explicit app-server session/settings/update request can set that distinct per-request override, which takes precedence over the model cap. There is no separate output-token CLI flag in this version. See the headless configuration and output-cap precedence.

The native time/token/export flags below are present in the audited 3.0.0 installation. Verify your own vibe --help before running them. Select the qualified-worker alias with active_model in reviewed configuration first; the 3.0 CLI has no --model flag. This example assumes an already isolated environment and reviewed project trust:

Terminal window
vibe --workdir /path/to/isolated-worktree --trust \
--agent auto-approve \
--enabled-tools read_file --enabled-tools grep \
--enabled-tools write_file --enabled-tools search_replace \
--prompt-file /path/to/task.txt \
--time-limit 600 --max-turns 12 --max-tokens 60000 \
--max-price 0.50 --output streaming \
--output-dir /path/to/private-run-artifacts

This allowlist deliberately has no shell, MCP, or child-agent tool. A trusted controller can run independently approved checks afterward. Add shell execution only inside an appropriate sandbox.

Cumulative token and price guards react to usage notifications. In the 3.0 implementation, a stop is requested when reported usage exceeds the budget; equality alone does not stop it. No remaining-token calculation shrinks the next response request. A completion or delayed notification can therefore overshoot the threshold. For resumed sessions, the run baseline excludes usage from earlier runs.

A CLI cost estimate uses configured prices; stale or missing prices undermine it. Native usage guards do not promise an exact provider-side token or monetary ceiling. Keep per-response caps and provider/account quotas alongside them. An external supervisor supplies a wall deadline and bounded kill grace independently of usage reporting. For self-hosted models priced at zero, token, time, and resource limits remain essential. See official execution guidance.

Text or JSON output may be emitted only after the run finishes. Streaming events help diagnose progress, but an event is not proof that the model completed useful work. Do not declare a job stuck solely because a buffered output file is empty.

Retain the session export, journal, stderr, baseline commit, exact model/settings, and termination reason in a private artifact directory. Distinguish a completed answer from a deadline, turn/token budget stop, truncated response, denied tool, provider error, or supervisor kill. Verify generated artifacts and executable checks; exit 0 or an assistant saying PASS is insufficient.

Start with one inference request at a time. Increase only after measuring latency, memory, and failure rate on the actual server and provider quota. A model server’s slot count is not evidence that it can run that many coding jobs efficiently.

Retries consume the same wall-clock budget. Inspect the actual error rather than assuming every long call is a rate limit. HTTP 429, HTTP 402, authentication failures, and an unreachable host require different responses. Avoid replacing an uncertain active job with a duplicate; reconcile its process and artifacts first.

Vibe can use a hosted API, a direct private endpoint, or a proxy. Read the selected provider’s api_base to determine which route matters. A stopped compatibility proxy is irrelevant to a direct route; it is a real dependency when the preset points at that proxy.

Aliases such as sonnet and opus can be compatibility labels for entirely different upstream models. Record the actual served identity. A successful inventory or health request establishes reachability, not successful inference, coding correctness, or account budget.

A private model endpoint alone does not prove offline operation. Audit utility/title models, compaction, account/model discovery, telemetry, update checks, connectors, MCP, hooks, and shell tools. Disable unused paths, remove broad credentials, and verify network denial at the execution boundary. Documentation MCPs intentionally use the network.

Qualify the exact configured worker with a fresh read/edit/test task before dispatching repository work. A deadline or disconnected host leaves the worker unqualified; rerun after restoring connectivity rather than publishing a quality score from that failure.

Recent changes

  1. docs(wiki): add coding agent approval and session flag references @sac
  2. docs(wiki): clarify Vibe limits and report bounded model screens sac
  3. Refresh Vibe setup and private server model guidance sac
  4. docs(wiki/ai-ml): document vibe -p headless gotchas + safe-dispatch template sac