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

# Quickstart: Install Sesame and Make Your First Request

> Install the Sesame CLI, register your device, and proxy your first authenticated API request — credentials stay server-side the whole time.

Go from a fresh machine to your first brokered request in under five minutes.

You'll manage your devices, API credentials (secrets), and request approvals from the **[Sesame dashboard](https://getsesame.dev)** — the steps below link you to it as you go.

**Before you start:** you'll need macOS (arm64/x86\_64) or Linux (x86\_64) and a [Sesame account](https://getsesame.dev) — plus Node.js if you want agent skills installed automatically.

***

## Steps

<Steps>
  <Step title="Install the CLI">
    Run the one-line installer:

    ```bash theme={null}
    curl -fsSL https://getsesame.dev/install.sh | sh
    ```

    The installer writes the `sesame` binary to `/usr/local/bin` by default. If that directory is not writable without `sudo`, it automatically falls back to `~/.local/bin`.

    If you see a `PATH` warning after installation, add the install directory to your shell profile:

    ```bash theme={null}
    # zsh
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

    # bash
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
    ```
  </Step>

  <Step title="Install agent skills">
    Agent skills teach supported AI agents (Claude Code, Codex, Cursor, OpenClaw, and 40+ others) to route their API calls through Sesame automatically — no prompt engineering or manual tool wiring required.

    Skills install via `npx`, so you'll need Node.js. If you don't have it yet:

    <CodeGroup>
      ```bash macOS (Homebrew) theme={null}
      brew install node
      ```

      ```bash Linux / macOS (nvm) theme={null}
      curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
      nvm install --lts
      ```
    </CodeGroup>

    Then add the skills:

    ```bash theme={null}
    npx skills add getsesame/skills
    ```

    <Check>
      Confirm it installed — the skill is just files on disk:

      ```bash theme={null}
      ls ~/.agents/skills/sesame && echo "✓ Sesame skill installed"
      ```

      If that lists files, the skill is in place — your agents will now route their API calls through `sesame request`.
    </Check>
  </Step>

  <Step title="Register your device">
    ```bash theme={null}
    sesame login
    ```

    This command does two things:

    1. Generates an **Ed25519 keypair** on your device. The private key never leaves your machine.
    2. Opens a **one-click claim URL** in your browser. Sign in with your Sesame account to bind the keypair to your identity and complete device registration.

    After you approve the claim in the browser, the CLI receives a signed JWT that it uses to authenticate every subsequent request.
  </Step>

  <Step title="Check device status">
    ```bash theme={null}
    sesame status
    ```

    The output shows your device fingerprint (the public key hash), the registered agents bound to this device, and the current token state. Confirm the fingerprint matches what you see in the Sesame dashboard under **Devices**.
  </Step>

  <Step title="List configured hostnames">
    ```bash theme={null}
    sesame hostnames
    ```

    This lists every API hostname that has a credential configured in your vault. If you have not added any credentials yet, visit the **Integrations** tab in the dashboard to connect a provider — Sesame's 70+ pre-built integrations make this a one-click step for common APIs.
  </Step>

  <Step title="Make an authenticated request">
    Send your request with `sesame request` instead of `curl` — and target a hostname **that appeared in the previous `sesame hostnames` step**. `sesame request` only attaches a credential for hosts you've already configured a secret for; pointing it at anything else will fail.

    <Warning>
      If the host you want isn't in your `sesame hostnames` list, configure its secret first, then come back to this step.

      Start with the CLI: `sesame secret create <name> --hostname <host>` returns a dashboard link where you paste the value (the CLI never accepts secret material). If that doesn't work, add the secret directly in the dashboard under [**Credentials → Secrets**](https://getsesame.dev/credentials/secrets) (the same path on your own broker's URL if you self-host).
    </Warning>

    The example below calls the Anthropic Messages API. **It's only an example** — substitute whichever host is in *your* list and the request/headers that API expects:

    ```bash theme={null}
    # api.anthropic.com here is illustrative — swap in a host from YOUR `sesame hostnames` output
    sesame request POST https://api.anthropic.com/v1/messages \
      -H "Content-Type: application/json" \
      -H "anthropic-version: 2023-06-01" \
      -d '{
        "model": "claude-sonnet-4-5",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "Hi"}]
      }'
    ```

    Sesame verifies your device identity, confirms the target hostname has a secret configured, injects the matching credential server-side, and forwards the request. The response comes back to your terminal exactly as it would from a direct `curl` call — minus any secret ever appearing on your side of the wire.

    <Note>
      The first time you target a new hostname, Sesame pauses the request and sends you an **approval prompt** via the Sesame app, the Sesame dashboard, or Telegram. Tap **Approve** to allow the request and allow future requests to that hostname from this device.
    </Note>

    <Tip>
      If the response is an authentication error from the upstream API (e.g. `401`, "invalid key"), the secret exists but its stored value is wrong, expired, or empty — Sesame attached it and the provider rejected it. Fix the value in the dashboard under **Credentials → Secrets**, then retry. A `denied by policy` error is different: the credential is fine, but the secret's access policy doesn't allow that method or path — adjust the policy on that secret instead.
    </Tip>
  </Step>

  <Step title="Enable browser notifications">
    Approvals are time-sensitive — a `sesame request` to a new hostname pauses until you approve it, and times out after 5 minutes. Turn on browser notifications so those prompts reach you without watching the terminal.

    Open [**Settings**](https://getsesame.dev/settings) (the same path on your own broker's URL if you self-host), go to the **Browser Notifications** section, and click **Enable browser notifications**. Accept the browser's permission prompt when it appears.

    You'll then get system-level approval requests — and security alerts — in this browser even when the Sesame tab is closed; clicking one jumps straight to the approval screen. (Approvals also go to the Sesame app and Telegram, so you can use whichever channel you prefer.)
  </Step>
</Steps>

***

## Install options

Use installer flags to pin a version, change the install prefix, or uninstall:

<CodeGroup>
  ```bash Default install theme={null}
  curl -fsSL https://getsesame.dev/install.sh | sh
  ```

  ```bash Specific version theme={null}
  curl -fsSL https://getsesame.dev/install.sh | sh -s -- --version v0.3.22
  ```

  ```bash Custom prefix theme={null}
  curl -fsSL https://getsesame.dev/install.sh | sh -s -- --prefix ~/.local/bin
  ```

  ```bash Uninstall theme={null}
  curl -fsSL https://getsesame.dev/install.sh | sh -s -- --uninstall
  ```
</CodeGroup>

<Warning>
  Sesame is pre-1.0 / alpha. If you pin a version in a shared or production environment, check the [changelog](https://getsesame.dev/changelog) before upgrading — breaking changes can occur between minor releases.
</Warning>