> ## 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.

**1. Install the CLI**

```bash theme={"system"}
npm i -g @usenaive-sdk/vetta-cli
vetta --version
```

> [!NOTE]
>
> Naive's API, SDK and CLI use the name `vetta` in their identifiers (`api.vetta.sh`,
> `@usenaive-sdk/vetta`, the `vetta` command). They're the same product. The package also
> installs a `naive` command that runs the same commands, so `naive login` is `vetta login`.

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](https://vetta.sh/docs/api/overview.md), so `curl` works before the CLI does.

**2. Authenticate**

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
```

> [!NOTE]
>
> `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.

**3. Start the plan**

A new organization needs a plan before anything outside billing answers. Standard is $20 a
        month with $20 of credit included, and starts with a 7-day free trial (card required); Pro is
$200 a month with $200 included. `subscribe` prints a hosted checkout link.

```bash theme={"system"}
vetta plan subscribe                # Standard; add --plan pro for Pro
vetta plan show                     # status: active once the checkout completes
```

See [Pricing](https://vetta.sh/docs/platform/pricing.md#plans).

**4. Add credits**

Billing is real US dollars, prepaid; the plan's included credit lands here too and rolls over.
`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](https://vetta.sh/docs/platform/billing.md).

**5. 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.

```bash theme={"system"}
AGENT=$(vetta agent create \
  --name nightly-triage \
  --model z-ai/glm-5.3-flash \
  --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.

> [!NOTE]
>
> **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.

**6. Run it and stream the output**

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`.

**7. Read the meter**

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](https://vetta.sh/docs/computer/index.md).

```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": "z-ai/glm-5.3-flash",
    "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](https://vetta.sh/docs/api/overview.md) for auth, pagination, idempotency and the shared error envelope.

> [card] [Next: how Naive Managed Agents works](https://vetta.sh/docs/how-managed-agents-is-built.md)
>
> Harness, runtime, tools — the three layers that make a finished task cheap.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.