# Quickstart

Get VeilCLI running and talk to your first agent in under 5 minutes.

---

## Prerequisites

- **Node.js ≥ 20.0.0** — check with `node --version`
- An **OpenAI-compatible API key** — [OpenRouter](https://openrouter.ai) works out of the box

---

## Step 1 — Install

```bash
npm install -g @newsails/veil-cli
```

Verify:
```bash
veil --version
# VeilCLI v0.1.0
```

---

## Step 2 — Create a Workspace

A workspace is any directory with a `.veil/` folder.

```bash
mkdir ~/my-workspace && cd ~/my-workspace
mkdir -p .veil/agents/hello
```

---

## Step 3 — Configure Auth

```bash
# Save your API key to the project workspace
veil login --key sk-or-v1-YOUR_KEY_HERE

# Or save it globally (shared across all workspaces)
veil login --key sk-or-v1-YOUR_KEY_HERE --global
```

This writes to `.veil/auth.json`:
```json
{
  "providers": {
    "openrouter": {
      "type": "openai",
      "base_url": "https://openrouter.ai/api/v1",
      "api_key": "sk-or-v1-..."
    }
  },
  "routing": {
    "default": "openrouter",
    "fallback": []
  }
}
```

You also need to specify the default model. Edit `.veil/auth.json` or set it in agent configs. The simplest approach — set it globally in `~/.veil/settings.json`:
```json
{
  "models": {
    "main": { "model": "moonshotai/kimi-k2.6" }
  }
}
```

Or set `"model"` in each agent's `agent.json`.

Any [OpenRouter model slug](https://openrouter.ai/models) works. Popular choices:
- `moonshotai/kimi-k2.6` — fast, capable, tool-calling
- `anthropic/claude-4-6-sonnet` — excellent reasoning
- `google/gemini-2.0-flash-001` — very fast
- `meta-llama/llama-3.3-70b-instruct` — open model

---

## Step 4 — Create Your First Agent

Create `.veil/agents/hello/agent.json`:

```json
{
  "name": "hello",
  "description": "A friendly conversational agent",
  "model": "moonshotai/kimi-k2.6",
  "temperature": 0.7,
  "reasoning": "medium",
  "memory": { "enabled": false },
  "modes": {
    "chat": { "enabled": true },
    "chat": { "enabled": true }
  }
}
```

Create `.veil/agents/hello/AGENT.md`:

```markdown
You are Hello, a friendly and concise assistant.

Be helpful, clear, and direct. Keep responses short unless asked for detail.
```

---

## Step 5 — Start the Server

```bash
cd ~/my-workspace
veil start
# VeilCLI v0.1.0 started on port 5050
# Project: /home/user/my-workspace
# Agents: 1 | PID: 12345
```

Options:
```bash
veil start --port 5051          # custom port
veil start --folder /other/dir  # different workspace
veil start --secret mytoken     # require auth header
```

---

## Step 6 — Chat!

```bash
# Check health
curl http://localhost:5050/health

# Send a chat message
curl -X POST http://localhost:5050/agents/hello/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What is 2 + 2?"}'
```

Response:
```json
{
  "sessionId": "sess_4f3a1b9c2d8e7f01",
  "message": {
    "role": "assistant",
    "content": "2 + 2 = 4."
  },
  "tokenUsage": { "input": 120, "output": 8, "cache": 0 }
}
```

Continue the conversation by passing `sessionId` back:
```bash
curl -X POST http://localhost:5050/agents/hello/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "And multiply that by 3?", "sessionId": "sess_4f3a1b9c2d8e7f01"}'
```

---

## Step 7 — Give Your Agent Tools

Agents can use tools (shell, files, web) inside any chat turn — great for anything that needs multiple LLM steps.

Update `agent.json` to allow some tools:
```json
{
  "name": "hello",
  "model": "moonshotai/kimi-k2.6",
  "modes": {
    "chat": {
      "enabled": true,
      "permissions": {
        "allow": ["read_file", "list_dir", "bash"]
      }
    }
  }
}
```

Then just chat — the agent runs the tools during its turn:
```bash
curl -X POST http://localhost:5050/agents/hello/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "How many files are in the current directory?"}'
```

---

## Interactive CLI Client

If you have the `connect.js` TUI client, you can explore everything interactively:

```bash
node /path/to/VeilCli_TESTS/cli-app/connect.js
```

Or jump straight to a chat session:
```bash
node connect.js chat hello
```

See [the connect.js README](../guide/05-cli.md#interactive-tui-client) for full usage.

---

## What's Next

- [Folder Structure](02-folder-structure.md) — understand every file in `.veil/`
- [Configuration](03-configuration.md) — all settings explained
- [Agent Configuration](04-agents.md) — full `agent.json` reference
- [Built-in Tools](06-tools.md) — what your agents can do