> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Create an agent, give it work, watch it, and read the meter.
Zero to a running agent in five steps. Every command on this page is tested verbatim against a live deploy.
```bash theme={"system"}
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](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](/docs/api/overview), so `curl` works before the CLI does.
The CLI stores a **profile** — a credential plus base URL — and never prints it back.
```bash theme={"system"}
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:
```bash theme={"system"}
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.
Billing is real US dollars, prepaid. `topup` prints a hosted checkout link — nothing is
credited until the payment settles.
```bash theme={"system"}
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](/docs/platform/billing).
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.
```bash theme={"system"}
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.
A session is one directly-controlled run: create it with its first message, then stream events.
```bash theme={"system"}
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:
```json theme={"system"}
{"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`.
Every dollar is metered per component, per agent, and per session.
```bash theme={"system"}
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:
```bash theme={"system"}
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](/docs/computer/index).
```bash theme={"system"}
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.
```bash theme={"system"}
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](/docs/api/overview) for auth, pagination, idempotency and the shared error envelope.
Harness, runtime, tools — the three layers that make a finished task cheap.