Quickstart

Zero to a running agent in five steps. Every command on this page is tested verbatim against a live deploy.

Install the CLI

npm i -g @usenaive-sdk/vetta-cli
vetta --version

Prefer not to install it globally? Every command below also works as npx @usenaive-sdk/vetta-cli ….The snippets below use jq to capture ids from JSON output (… | jq -r .id) — install it, or copy the agt_... / ses_... ids from the output by hand.Working with a coding agent? Point it at the onboarding manifest — https://usenaive.ai/skill.md — and it will walk your operator through everything on this page. Every command below is also a REST call against the API, so curl works before the CLI does.

Authenticate

The CLI stores a profile — a credential plus base URL — and never prints it back.

vetta login --api-key sk_...            # an API key: the CI path
vetta login --email you@example.com --password '…'   # a person: signs in, stores a session token

Confirm which organization you are pointed at before you spend anything:

vetta whoami

VETTA_API_KEY and VETTA_API_BASE_URL override the stored profile for a single command, so scripts and CI never need a config file at all.

Add credits

Billing is real US dollars, prepaid. topup prints a hosted checkout link — nothing is credited until the payment settles.

vetta credits topup --usd 50        # prints a hosted checkout link
vetta credits show

Your organization is the billing entity; every agent draws from the same balance. See Billing.

Create an agent

An agent bundles a model, a system prompt, a completion window, and a budget — the budget is required, so every agent has a spend cap from birth.

AGENT=$(vetta agent create \
  --name nightly-triage \
  --model zai-org/GLM-5.2-FP8 \
  --budget-usd 50 --max-task-usd 5 --budget-period month \
  --window immediate \
  --system "You are a concise triage agent. You have a Linux sandbox. Do the work, then answer in one short paragraph." \
  | jq -r .id)

echo "$AGENT"     # agt_...

Later commands take the id, not the name. vetta models list prints the model ids and the completion windows each supports.

You do not attach a computer to an agent. A session provisions its own fresh sandbox only when the agent’s tools need one — a text-only agent pays nothing for a box it won’t use.

Run it and stream the output

A session is one directly-controlled run: create it with its first message, then stream events.

SID=$(vetta session create \
  --agent "$AGENT" \
  --message "Create notes.md in your home directory containing 'hello from vetta', read it back, and tell me what it says." \
  | jq -r .id)

vetta session stream --session "$SID"

The stream is the whole truth of the run — every model call with its quote, every tool call, the reply, the usage line:

{"seq":4,"type":"tool.started","data":{"name":"write","args":{"path":"~/notes.md","content":"hello from vetta"}}}
{"seq":5,"type":"tool.completed","data":{"name":"write","output":"Successfully wrote 16 bytes","is_error":false}}
{"seq":13,"type":"message.completed","data":{"role":"assistant","content":"Done — notes.md contains exactly: hello from vetta."}}
{"seq":14,"type":"session.usage","data":{"consumed_micro_usd":2023,"active_seconds":7,"tool_calls":2}}
{"seq":15,"type":"session.idle","data":{"stop_reason":"end_turn"}}

Follow up with vetta session send --session "$SID" --text "…"; resume a dropped stream with --after-seq.

Read the meter

Every dollar is metered per component, per agent, and per session.

vetta agent spend "$AGENT" --by component
vetta session usage --session "$SID"

Files the agent published during the run are listed with vetta file list --scope session --session "$SID".

Create an API key for programmatic access

Code authenticates with a scoped API key — the secret is returned once and never again:

vetta keys create --name quickstart --scopes agents:write,sessions:write
export VETTA_API_KEY="sk_...the secret shown once..."

Driving a sandbox directly

A computer is a disposable Linux sandbox you can drive yourself, independently of any agent. Pause it to bill storage only. Sessions always get their own sandbox — a computer you create here is never handed to one. See the Computer reference.

vetta computer create --name box --vcpu 2 --memory-mb 4096 --disk-gb 20
vetta computer exec cmp_... --command 'pwd; ls -la'
vetta computer pause cmp_...

The same arc over HTTP

The CLI is a thin client over the REST API; the whole arc above is a few requests.

export VETTA_API_KEY="sk_..."
export BASE="https://api.vetta.sh"   # or $VETTA_API_BASE_URL to point elsewhere

AGENT=$(curl -sS "$BASE/v1/agents" \
  -H "Authorization: Bearer $VETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "nightly-triage",
    "model": "zai-org/GLM-5.2-FP8",
    "window": "immediate",
    "system": "You are a concise triage agent.",
    "budget": { "cap_micro_usd": 50000000, "max_task_micro_usd": 5000000, "period": "month" }
  }' | jq -r .id)

SESSION=$(curl -sS "$BASE/v1/sessions" \
  -H "Authorization: Bearer $VETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"agent_id\": \"$AGENT\", \"message\": \"Summarize what you can see in your sandbox.\"}" \
  | jq -r .id)

curl -sN "$BASE/v1/sessions/$SESSION/stream" -H "Authorization: Bearer $VETTA_API_KEY"

See the API overview for auth, pagination, idempotency and the shared error envelope.

Next: how Vetta works

Harness, runtime, tools — the three layers that make a finished task cheap.

Get started

Capabilities at a glance

Platform

Create an API key for programmatic access

Driving a sandbox directly

The same arc over HTTP

Next: how Vetta works

​Create an API key for programmatic access

​Driving a sandbox directly

​The same arc over HTTP

Next: how Vetta works

Create an API key for programmatic access

Driving a sandbox directly

The same arc over HTTP