VTX Macro CLI

Command-line and MCP access for VTX Macro automation.

Install or update

npm install -g @vtxmacro/cli
vtx --version

vtx and vtx-mcp keep themselves current without administrator rights. At most every few hours a start checks npm latest and the VTX API's minimum supported version, installs a newer release with the same integrity and version checks as the service updater into ~/.vtx/cli-update (VTX_HOME), and runs the same command on it. vtx-mcp stages in the background and switches at its next start. A new release that does not start is rolled back and skipped until a newer one appears. Below the minimum, a CLI that cannot update stops with the update command. VTX_CLI_AUTO_UPDATE=0 turns this off; npx and project installs are left to their owner.

The host supports Windows x64 and Linux x64, including WSL. The package installs the exact supported OpenAI Codex runtime, GitHub Copilot SDK, official DeepSeek Harness package wave, Pi SDK package wave, and Grok Build runtime. The VTX host verifies the Codex runtime's version and digest before use; it does not borrow a Codex binary from PATH or an editor extension. For Windows-login auto-start, install and configure the CLI from native Windows; a CLI installed only inside WSL cannot start the WSL virtual machine at login. New service installations use a private verified launcher. At login, every service start, and periodically while running, it checks the official npm registry and verifies the exact release integrity and installed CLI version in a new versioned directory. Before switching, it stops new admission and lets active Provider calls and Agent turns finish while keeping heartbeats alive. It selects the candidate only after every configured worker reports ready. A stable recovery launcher starts the versioned updater and keeps the previous working release. Routine updates do not replace this recovery launcher. If activation fails or the updated process exits unexpectedly, it rejects that release and restores the previous runtime. The service keeps the active release and its recovery release. If the update check is unavailable, it keeps the last verified runtime. An intentionally stopped service stays stopped and makes no update request. Hosts installed before this private launcher need one final normal npm update and service reinstall to adopt it. Startup-only launchers adopt background checking after their next normal start activates a release that includes it; publishing a release cannot replace an older process that is already running.

Configure

export VTX_PROFILE_ID="<profile-id>"
vtx auth login --scopes read,bot:control

CLI

vtx --json auth whoami
vtx --json bots status
vtx --profile <profile-id> runtime run --follow

MCP

Configure your MCP-compatible agent app to start:

vtx-mcp

The CLI and MCP server use the same saved token and environment variables.

Agent inference hosts

Both paths use a separate least-privilege insights:inference OAuth grant. VTX never receives an agent vendor password, OAuth token, or subscription credential.

• Background services: OpenAI Codex, Claude Code, GitHub Copilot, DeepSeek Harness, Grok Build, Pi. These integrations can keep serving VTX after the setup chat ends. Keep the host computer on and its service running.
• Automatic foreground bridge: Exo. The bridge serves VTX automatically while its process stays open.
• Foreground agent integrations: Amp, Auggie, Cursor, Gemini CLI, Google Antigravity, Hermes Agent, JetBrains Junie, Kiro CLI, OpenClaw, OpenCode, Qwen Code, Warp Oz. Keep the harness session and its VTX foreground host loop open. Available modes depend on the connected model’s advertised capabilities.

These groups describe how an integration runs, not a test grade. Limitations are listed in the Insights harness guide. Any recorded acceptance applies only to its tested mode and date; it does not prove current provider availability.

Durable inference hosts

Codex remains the reference implementation and its existing App Server, authentication, quota, recovery, and provider-mode path are unchanged. GitHub Copilot uses the official SDK and validates final text against VTX's immutable schema. An uncertain interrupted Copilot call is quarantined as outcome_unknown and is never blindly repeated. A different adapter cannot replace an installed Codex instance; it needs a distinct instance and VTX grant. VTX resolves the package-owned pinned Copilot platform runtime explicitly and rejects an auto-only catalog because it cannot prove the effective model.

Grok Build is a durable adapter using its package-owned official runtime and an isolated local Grok OAuth session. Run vtx inference-host grok-login --instance grok-1 after vtx inference-host login --instance grok-1, then vtx inference-host service install --adapter grok-build --instance grok-1. Provider mode has no tools; Main Agent mode exposes only assignment-scoped VTX tools. Structured decisions, model identity, and usage are validated. Interrupted requests with an uncertain outcome are fenced; same-attempt recovery is not supported.

Claude Code is a durable adapter over your own installed Claude Code CLI and a Claude subscription. Install Claude Code first (on Windows, its native installer), then run vtx inference-host login --instance claude-1 and vtx inference-host claude-login --instance claude-1. Claude Code opens its own sign-in page; approve it with the subscription account. If no page opens, open the printed link and paste the code Claude shows into the same terminal. The login is a separate one kept only for that host, and VTX never reads it. Then run vtx inference-host service install --adapter claude-code --instance claude-1. Runs count toward the subscription's usage limits; the host refuses an API-key or token login. Provider mode has no tools; Main Agent mode exposes only assignment-scoped VTX tools. When a usage limit is reached, new work moves to the next fallback host until it resets.

An explicitly capable model from a background service listed above can also control Main in Agent mode using the same VTX OAuth grant and its own local adapter-specific vendor credential: ChatGPT, Copilot, Grok, or Claude login, or a DeepSeek or Pi provider API key. VTX assigns the running bot and supplies canonical Agent instructions. The assigned runtime keeps a durable thread, requests assignment-scoped data as needed, and chooses whether to submit a structured decision. The model chooses its next wake through its adapter. A wake never forces HOLD or trading JSON. Review and Screener remain Provider-only.

Before the first Codex login, enable Device code authorization for Codex in ChatGPT Security settings. Only enter a device code from a login you initiated, and never share it. The automated host reads the authenticated Codex model picker and advertises every visible model with that model's exact display name, default effort, and supported reasoning efforts. Hidden Codex entries are not exposed. Before starting a Trader, confirm that the VTX AI page shows the intended authenticated ChatGPT email and plan. The host reads the live Codex account window: a reached limit pauses new dispatch until its reported reset, while a transient throttle uses a short bounded cooldown. The selected AI model row estimates the open VTX profile's attributable membership burn rate for that subscription, expressed as equivalent percentage points per hour, day, and seven days. Account-wide quota percentages remain in safe host diagnostics instead of the profile-scoped selector.

vtx inference-host login
vtx inference-host codex-login
vtx inference-host doctor --json
vtx inference-host service install
vtx inference-host service status --json
vtx inference-host service logs
vtx inference-host logout
vtx inference-host codex-logout
vtx inference-host revoke

For Copilot, sign in with the official Copilot CLI, then run:

vtx inference-host login --instance copilot-1
vtx inference-host doctor --adapter copilot --instance copilot-1 --json
vtx inference-host service install --adapter copilot --instance copilot-1

For DeepSeek Harness, import the API key through stdin so it never appears in process arguments, then install a distinct durable instance:

vtx inference-host login --instance deepseek-1
vtx inference-host deepseek-login --instance deepseek-1 < /private/path/deepseek.key
vtx inference-host doctor --adapter deepseek-harness --instance deepseek-1 --json
vtx inference-host service install --adapter deepseek-harness --instance deepseek-1

The DeepSeek key remains in the local OS credential store or the explicitly selected private-file fallback; it is never written to the service manifest or sent to VTX. Provider mode is tool-less. Main Agent mode uses a durable Harness session with only the three assignment-scoped VTX tools. Review and Screener remain Provider-only. An Agent dispatch whose provider outcome cannot be proved is durably fenced and is not repeated after a service restart. Inspect status --json, doctor --json, and service logs; revoke and relink the exact instance after reconciling an ambiguous fence. An authentication fence clears only after a successful replacement key import. Quota and rate-limit failures honor their provider retry time or a bounded local cooldown.

For Pi, use a separate instance and import one provider API key privately:

vtx inference-host login --instance pi-1
vtx inference-host pi-login --provider openai --instance pi-1 < /private/path/provider.key
vtx inference-host doctor --adapter pi --instance pi-1 --json
vtx inference-host service install --adapter pi --instance pi-1

Pi uses the package-owned SDK and exact provider/model identities. The existing Provider / Agent controls apply: Provider receives VTX's prompt and has no tools; Main Agent keeps an isolated session and the canonical VTX assignment tools. The initial qualified models use an OpenAI API key; the release embeds VTX's configured exact model IDs and SDK capability mappings. API compatibility alone does not qualify a provider. Ordinary Pi credentials, extensions, project instructions, and sessions are not imported. Subscription OAuth is not enabled by this adapter. Calls with uncertain outcomes remain fenced after restart; conversation persistence does not imply same-attempt recovery. Uninstall the exact service instance and settle pending work before removing its key with pi-logout --instance pi-1.

To connect another Codex subscription to the same VTX account, repeat the login and service-install commands with a stable local name such as --instance codex-2. Each named instance has an isolated VTX grant, Codex home, credential file, runtime state, recovery state, and worker; one per-user OS supervisor runs all installed instances. Use service status --json to inspect the installed workers. The installer rejects duplicate authenticated ChatGPT emails and fails closed when it cannot prove multiple subscriptions are distinct. Use service uninstall --instance <name> to remove one worker; unqualified service uninstall removes the whole supervisor. The legacy unqualified host commands continue to target default.

On native Windows, if service status or logs show that guarded recovery is blocking one installed subscription, recover that exact instance without rebooting:

vtx inference-host service recover --instance <name> --force-recovery --json

Recovery is intentionally noninteractive and requires both --instance and --force-recovery; --json changes only the output format. The shared supervisor briefly quiesces so every installed worker can stop cooperatively, then VTX restores its previous desired state and the same peer subscriptions. The command never kills an arbitrary process, logs either account out, changes VTX profile settings, or controls a Trader. If any package-owned VTX automation is still live, recovery fails closed and preserves its evidence.

For each VTX profile and lane, Host #1 is selected. Provider-mode calls may continue through later compatible hosts in the saved Host cascade order. Agent mode keeps its durable thread and assignment on Host #1 and fences a failure instead of automatically transferring it. Distinct computers may use the same authenticated subscription; when account identity is reported, provider quota remains account-level and quota exhaustion skips only positively matching identities. Unusable authentication and exhausted recoverable Provider failures can advance the same logical call. VTX never changes provider, model, effort, or response mode, and never cascades a bad request, policy rejection, or uncertain dispatch outcome.

Automated hosts do not impose a provider-specific profile-count or concurrency limit by default. Set an explicit positive integer with --max-concurrency when you want a local limit. Every active turn still consumes capacity from its adapter-specific provider account or API key; unlimited local admission does not guarantee provider capacity. Codex uses its reported live subscription gate and cooldown. DeepSeek Harness is API-billed and does not claim a stable account identity or provider rate-limit window. Updating from an older bounded host removes its previous numeric limit; run service install --max-concurrency <positive-integer> only to add one back.

Every durable host uses a separate least-privilege insights:inference OAuth grant. Codex additionally keeps its ChatGPT subscription login in a dedicated private Codex home; Copilot uses its official cached user login; DeepSeek Harness keeps its API key in the local VTX credential boundary. No vendor credential is written to the VTX service manifest. The per-user OS service starts immediately, starts again at login, and reconnects after sleep, network loss, or a worker exit. Stopping a VTX bot leaves the provider online and idle. Use vtx inference-host run only for foreground diagnostics. VTX logout/revoke and Codex logout are intentionally separate operations. JSON foreground and service logs include safe concurrency, latency, token, failure-code, and cooldown events without prompts, responses, or credentials. Use service logs --instance <name> to isolate one subscription.

Use vtx inference-host --help for command discovery. The VTX login verifies that the selected credential store can read back the exact saved grant. If an OS credential store such as Windows Credential Manager cannot retain it, VTX revokes the new remote grant and fails with an actionable error. Retry with the supported private-file store by setting VTX_INFERENCE_HOST_CREDENTIAL_STORE=file before running vtx inference-host login again. In PowerShell use $env:VTX_INFERENCE_HOST_CREDENTIAL_STORE="file"; in bash use export VTX_INFERENCE_HOST_CREDENTIAL_STORE=file.

The browser callback shows a VTX authorization-complete page. If a browser extension instead shows ERR_BLOCKED_BY_CLIENT but the CLI reports logged_in and doctor reports credential-present, only the local confirmation page was blocked; the grant succeeded.

Any compatible agent harness

Compatible agents that can run shell commands can use their existing first-party session without a VTX-owned vendor adapter:

vtx inference-host login
vtx inference-host agent-connect \
  --adapter <lowercase-harness-id> \
  --model <exact-model-id> \
  --model-label "<display label>" \
  --effort <reasoning-effort> \
  --json
vtx inference-host agent-run
vtx inference-host agent-next --wait-seconds 50 --json

That is the Provider loop. agent-next returns separate exact system_prompt, user_prompt, context_json, and output_schema_json fields. The agent reasons in its own session, then writes one JSON object to agent-complete stdin. The CLI reports its actual release version and negotiates foreground_v1 Provider freshness. Prewarm the harness before requesting work. For Server Mode jobs, the handoff includes provider_dispatch_not_after, provider_dispatch_local_not_after, and provider_dispatch_freshness_remaining_ms; the local deadline and remaining budget account conservatively for RPC time and pending-request replay. Enforce both deadlines immediately before the real provider request. If either expires before dispatch, do not send stale work: use agent-fail with dispatch_outcome: not_dispatched, failure_category: freshness, failure_code: provider_dispatch_freshness_expired, and retryable: false. Completion contains a result string; negotiated server jobs also require provider_dispatched_at, the ISO 8601 timestamp captured at provider request entry. This is harness-reported evidence, not provider attestation. If the harness exposes exact token usage, include the published usage object; otherwise VTX records usage as explicitly unavailable. For agent-fail, choose the truthful dispatch state and set retryable true only when a fresh attempt is safe:

{"dispatch_outcome":"not_dispatched","failure_category":"adapter","failure_code":"harness_unavailable","retryable":true}
{"dispatch_outcome":"confirmed_dispatched","failure_category":"adapter","failure_code":"no_reliable_result","retryable":false}
{"dispatch_outcome":"outcome_unknown","failure_category":"transport","failure_code":"dispatch_confirmation_lost","retryable":false}

Use not_dispatched only when no harness inference began, confirmed_dispatched when it began but returned no trustworthy result, and outcome_unknown when dispatch itself cannot be confirmed. Pipe exactly one object to vtx inference-host agent-fail --json.

For Agent mode on an explicitly capable Main model, VTX supplies only the assignment, allowed data contract, and normal decision schema. The foreground agent chooses its own cadence and may request zero, one, or many data calls:

vtx inference-host agent-assignment-next --wait-seconds 50 --json
vtx inference-host agent-review-begin --json
vtx inference-host agent-data-call --json
vtx inference-host agent-decision-submit --json
vtx inference-host agent-decision-status --json
vtx inference-host agent-assignment-heartbeat --json
vtx inference-host agent-assignment-release --json

agent-assignment-next returns the exact output_schema, data capabilities, wake bounds, and decision_input shape. Submit a candidate matching that schema plus provenance with source: "external_agent", a stable agent_run_id, and the requested and actual model and reasoning effort. Use agent-decision-status after an uncertain submit response. Use agent-assignment-release only when intentionally ending the foreground Agent session; agent-assignment-heartbeat maintains the assignment lease. Heartbeat metadata is not evidence that market data was checked.

For recurring checks, ask your harness to run this Agent workflow at the desired cadence using its own scheduling facility. On each wake, fetch current VTX data, inspect source timestamps, and decide whether to submit trading JSON. A check may end without submitting anything, including HOLD. VTX does not configure a second scheduler, and saved profile trading interval does not schedule Agent turns. Keep agent-run open for heartbeats; it does not fetch market data or wake or restart your harness.

Use a single active turn for the assignment. Long turns, sleep, outages, and harness scheduling limits can delay checks; report missed checks and resume with fresh data instead of replaying old scheduled work. Continuous operation requires the harness and its host to remain available. Record actual successful read times and source timestamps to verify cadence and freshness.

prompt.variables discovers every canonical trading prompt variable; prompt.context reads selected names or all names for one owned profile. Disabled indicators are available request-locally without settings changes. Values share provider calculations, format instructions and unavailable semantics, including future variables. Full ordinary Insights MCP access and external tools remain separate authorized harness connections; the inference grant does not expand into account-wide mutation permission.

Exo foreground trading inference

Exo means exoharness/exo. VTX runs a dedicated Exo trading harness automatically in Provider and Main Agent modes. It is a foreground integration on Linux or WSL, not a durable service or native Exo MCP client. Keep the run command open; no separate keeper or manual job shuttling is needed. Review and Screener remain Provider-only.

Prepare the supported Exo source revision and its upstream dependencies:

git clone https://github.com/exoharness/exo.git
cd exo
git checkout c5c1963a3445417e64938c139da88edd9154075d
pnpm install --frozen-lockfile
cargo build --release -p exo

Use a separate VTX instance and import its vendor key privately:

vtx inference-host login --instance exo-1
vtx inference-host exo-login --provider openai --instance exo-1 < /private/path/provider.key
vtx inference-host doctor --adapter exo --exo-root /path/to/exo --instance exo-1 --json
vtx inference-host run --adapter exo --exo-root /path/to/exo --instance exo-1

Use --provider venice instead to import a Venice key into its own instance. The host advertises only the imported provider's qualified models and efforts. Venice initially supports Gemma 4 31B IT with thinking disabled (none); OpenAI supports the release-qualified Responses routes. VTX OAuth remains in the VTX process and credential store. Exo receives the complete Provider prompt or only assignment-scoped Agent tools, without stock shell, self-modification, installed tools, or ambient conversation context. Interrupted work with an unknown outcome is fenced rather than repeated. After stopping and resolving pending work, remove the vendor key with exo-logout --instance exo-1.

Amp, Auggie, Cursor, Gemini CLI, Google Antigravity, Hermes Agent, JetBrains Junie, Kiro CLI, OpenClaw, OpenCode, Qwen Code, Warp Oz use the explicit foreground agent path. Their setup and specific limitations are listed in the public Insights matrix. A successful foreground test does not establish background-service support.

Keep agent-run open in a separate terminal while the foreground host should remain available. Use the Provider job loop for Main, Review, or Screener, or the Agent assignment loop for an explicitly capable Main model. The independent keeper preserves truthful liveness while the harness reasons. Both loops support normally running VTX Client Mode or Server Mode bots. Server Mode keeps the normal VTX call fee. Client Mode has no VTX platform fee. Neither mode falls back to another model when the agent host is unavailable.

After any approved Trader start, use vtx --profile <profile-id> bots status to confirm the normal Trader remains running. If it returns to Stopped, use vtx --profile <profile-id> runtime events to read the latest error before one controlled retry. A start receipt or a brief Live label is not proof of a running bot.

Remove

First release any foreground Agent assignment, uninstall any durable service, stop any foreground run or agent-run process, revoke the VTX inference grant, then uninstall the package. Cleanup refuses while a foreground host process still owns the host. Automated Codex users should also remove the dedicated Codex login:

vtx inference-host service stop
vtx inference-host service uninstall
vtx inference-host revoke
# Automated Codex host only:
vtx inference-host codex-logout
npm uninstall -g @vtxmacro/cli

If an older failed login left no local credential to revoke, disconnect that inactive inference grant from Connected Agent Apps on the VTX Insights page before logging in again.