Vantage documentation

Agent RPC and CLI

Exact local RPC and CLI contract. The Unix socket belongs to the running Vantage process, is permissioned to the same OS user, and is the authoritative interface beneath the CLI.

Envelope

{"version":1,"id":"req-42","method":"browser.tabs","params":{}}

Success: {"version":1,"id":"req-42","ok":true,"result":...}. Failure: {"version":1,"id":"req-42","ok":false,"error":{"code":"...","message":"..."}}. One newline-delimited request is sent per connection.

CLI grammar

vant agent [--json] status
vant agent [--json] version
vant agent [--json] capabilities
vant agent tabs
vant agent open URI [TAB]
vant agent snapshot [TAB]
vant agent click REF [TAB]
vant agent fill REF VALUE [TAB]
vant agent fetch URL [OPTIONS_JSON]
vant agent diagnostics [TAB]
vant agent events
vant agent watch
vant agent call METHOD [JSON]
vant agent js [--file FILE|-|SCRIPT]

Exit status: 0 success, 1 runtime/RPC failure, 2 invalid CLI usage. Default output prints the result only; --json prints the complete envelope. call is the universal escape hatch.

Examples

vant agent tabs
vant agent open https://example.com 1
vant agent snapshot 1
vant agent click @e2_5 1
vant agent fill @e2_7 'hello world' 1
vant agent fetch https://api.example.com/status
vant agent call page.inspect '{"tab_id":1,"kind":"metadata"}'
vant agent js 'document.title'

Method discovery

vant agent capabilities
vant agent call describe '{}'
vant agent call describe '{"name":"page.snapshot"}'

Error model

RPC errors include method_not_found, invalid_request, request_too_large, not_found, timeout, javascript_error, fetch_error, navigation_rejected, navigation_external, invalid_param_type, invalid_property, cookie_error and screenshot_error. Semantic interaction failures are returned inside the method result as stale_or_missing, disabled or hidden.

Boundaries

Inbound requests are bounded to 1 MiB. RPC operations are bounded; agents should not use RPC as a bulk-file transport. net.fetch separately bounds returned response bodies. A timeout does not mean an arbitrary non-idempotent operation is safe to repeat.

Direct client

python3 tools/vant_agent.py browser.tabs '{}'
python3 tools/vant_agent.py page.snapshot '{"tab_id":1}'
python3 tools/vant_agent.py net.fetch '{"url":"https://api.example.com/status"}'

Integrations should prefer the Unix RPC directly when process-spawning the CLI for every call is undesirable. Cortex, Warden, Codex, OpenCode, scripts and custom agents can share the same protocol without a Gantry dependency.

Concurrency

Multiple local clients are accepted concurrently. Requests touching Vantage/WebKit are dispatched on the application main context. IDs are never retargeted to make a race appear successful. If another controller closes a tab, expect not_found.

Stability

Protocol 1 is stable. Additive optional fields/methods are compatible. Use discovery rather than hard-coding a complete capability set forever.