> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vestauth/vestauth/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get your first Vestauth agent running in 2 minutes

## Installation

Install Vestauth globally via npm:

```bash theme={null}
npm i -g vestauth
```

<Tip>
  For other installation methods, see the [Installation](/installation) guide.
</Tip>

## Create Your First Agent

Initialize a new agent in your current directory. This creates a `.env` file with your agent's cryptographic identity.

<Steps>
  <Step title="Initialize the agent">
    Run the init command to generate your agent's keypair:

    ```bash theme={null}
    vestauth agent init
    ```

    You'll see output like:

    ```bash theme={null}
    ✔ agent created (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)
    ⮕ next run: [vestauth agent curl https://api.vestauth.com/whoami]
    ```

    <Note>
      Your agent's identity is stored in `.env` with three values:

      * `AGENT_UID` - Your agent's unique identifier
      * `AGENT_PUBLIC_JWK` - Your public key (safe to share)
      * `AGENT_PRIVATE_JWK` - Your private key (keep secret!)
    </Note>
  </Step>

  <Step title="Verify your agent identity">
    Make your first authenticated request to the `whoami` endpoint:

    ```bash theme={null}
    vestauth agent curl https://api.vestauth.com/whoami --pp
    ```

    The `--pp` flag pretty-prints the JSON response:

    ```json theme={null}
    {
      "uid": "agent-4b94ccd425e939fac5016b6b",
      "kid": "B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I",
      "public_jwk": {
        "crv": "Ed25519",
        "x": "py2xNaAfjKZiau-jtmJls6h_3n8xJ1Ur0ie-n9b8zWg",
        "kty": "OKP",
        "kid": "B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I"
      },
      "well_known_url": "https://agent-4b94ccd425e939fac5016b6b.api.vestauth.com/.well-known/http-message-signatures-directory"
    }
    ```

    <Tip>
      The response shows your agent's public identity and the `.well-known` URL where tools can discover your public key.
    </Tip>
  </Step>

  <Step title="Call your first tool">
    Let's write a file using the SFS (Simple File System) tool:

    ```bash theme={null}
    vestauth agent curl https://sfs.vestauth.com/write -d '{"filepath":"/hello.md", "content":"Hello from my agent!"}'
    ```

    Now list your files:

    ```bash theme={null}
    vestauth agent curl https://sfs.vestauth.com/list --pp
    ```

    And read the file back:

    ```bash theme={null}
    vestauth agent curl https://sfs.vestauth.com/read -d '{"filepath":"/hello.md"}'
    ```

    <Note>
      Every request is cryptographically signed with your agent's private key. The tool verifies your identity before executing.
    </Note>
  </Step>
</Steps>

## Understanding Agent Identity

Let's look at what `vestauth agent init` created in your `.env` file:

```ini .env theme={null}
AGENT_UID="agent-4b94ccd425e939fac5016b6b"
AGENT_PUBLIC_JWK='{"crv":"Ed25519","x":"py2xNaAfjKZiau-jtmJls6h_3n8xJ1Ur0ie-n9b8zWg","kty":"OKP","kid":"B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I"}'
AGENT_PRIVATE_JWK='{"crv":"Ed25519","d":"Z9vbwN-3eiFMVv_TPWXOxqSMJAT21kZvejWi72yiAaQ","x":"py2xNaAfjKZiau-jtmJls6h_3n8xJ1Ur0ie-n9b8zWg","kty":"OKP","kid":"B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I"}'
```

<Warning>
  **Never share your `AGENT_PRIVATE_JWK`!** This is your agent's secret key. Anyone with access to it can impersonate your agent.
</Warning>

### How Signing Works

When you run `vestauth agent curl`, it automatically:

1. Reads your private key from `.env`
2. Signs the HTTP request with cryptographic headers
3. Sends the signed request to the tool

You can peek at the signed headers:

```bash theme={null}
vestauth agent headers GET https://api.vestauth.com/whoami --pp
```

```json theme={null}
{
  "Signature": "sig1=:d4Id5SXhUExsf1XyruD8eBmlDtWzt/vezoCS+SKf0M8CxSkhKBtdHH7KkYyMN6E0hmxmNHsYus11u32nhvpWBQ==:",
  "Signature-Input": "sig1=(\"@authority\");created=1770247189;keyid=\"B0u80Gw28W9U2Jl5t_EBiWeBajO2104kOYZ9Ikucl5I\";alg=\"ed25519\";expires=1770247489;nonce=\"NURxn28X7zyKJ9k5bHxuOyO5qdvF9L5s2qHmhTrGUzbwGSIoUCHmwSlwiiCRgTDGuum83yyWMHJU4jmrVI_XPg\";tag=\"web-bot-auth\"",
  "Signature-Agent": "sig1=agent-4b94ccd425e939fac5016b6b.api.vestauth.com"
}
```

These headers follow the [RFC 9421](https://datatracker.ietf.org/doc/rfc9421/) specification for HTTP Message Signatures.

## Try More Tools

<CardGroup cols={2}>
  <Card title="SFS - Simple File System" icon="folder">
    ```bash theme={null}
    # Write files
    vestauth agent curl https://sfs.vestauth.com/write \
      -d '{"filepath":"/notes.txt", "content":"My notes"}'

    # List files
    vestauth agent curl https://sfs.vestauth.com/list

    # Delete files
    vestauth agent curl https://sfs.vestauth.com/delete \
      -d '{"filepath":"/notes.txt"}'
    ```
  </Card>

  <Card title="GEO - Location" icon="location-dot">
    ```bash theme={null}
    # Get latitude and longitude
    vestauth agent curl https://geo.vestauth.com/geo --pp
    ```
  </Card>

  <Card title="AS2 - Secret Storage" icon="key">
    ```bash theme={null}
    # Set a secret
    vestauth agent curl https://as2.dotenvx.com/set \
      -d '{"API_KEY":"secret-value"}'

    # Get all secrets
    vestauth agent curl https://as2.dotenvx.com/get --pp
    ```
  </Card>

  <Card title="Docle - Email Verification" icon="envelope">
    ```bash theme={null}
    # Verify an email address
    vestauth agent curl https://docle.co/api/verify \
      -d '{"emails":["test@example.com"]}' --pp
    ```
  </Card>
</CardGroup>

## Key Rotation

Rotate your agent's keys while keeping the same identity:

```bash theme={null}
vestauth agent rotate
```

```bash theme={null}
✔ agent keys rotated (.env/AGENT_UID=agent-4b94ccd425e939fac5016b6b)
⮕ next run: [vestauth agent curl https://api.vestauth.com/whoami]
```

This generates new public and private keys but preserves your `AGENT_UID`.

## Using Vestauth in Code

You can use Vestauth programmatically in your JavaScript/TypeScript applications:

<CodeGroup>
  ```javascript Initialize Agent theme={null}
  const vestauth = require('vestauth')

  // Initialize a new agent
  const result = await vestauth.agent.init()
  console.log(result.AGENT_UID)
  // agent-4b94ccd425e939fac5016b6b
  ```

  ```javascript Generate Headers theme={null}
  const vestauth = require('vestauth')

  // Generate signed headers for a request
  const headers = await vestauth.agent.headers(
    'GET',
    'https://api.vestauth.com/whoami'
  )

  console.log(headers)
  // { Signature: 'sig1=:...', ... }
  ```

  ```javascript Using Primitives theme={null}
  const vestauth = require('vestauth')

  // Generate a keypair
  const { publicJwk, privateJwk } = vestauth.primitives.keypair()

  // Create signed headers
  const headers = vestauth.primitives.headers(
    'POST',
    'https://example.com/api',
    privateJwk,
    'agent-123',
    'https://api.vestauth.com'
  )
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Explore Tools" icon="wrench" href="/concepts/tools">
    Learn about all available first-party and third-party tools
  </Card>

  <Card title="Build Your Own Tool" icon="hammer" href="/advanced/building-tools">
    Create authenticated APIs with `vestauth.tool.verify()`
  </Card>

  <Card title="Self-Host Vestauth" icon="server" href="/self-hosting/overview">
    Run your own Vestauth infrastructure
  </Card>

  <Card title="Advanced CLI Usage" icon="terminal" href="/cli/overview">
    Master the Vestauth CLI commands
  </Card>
</CardGroup>