{% extends "base.html" %} {% block title %}Setup local agent — {{ config.INSTANCE_NAME }}{% endblock %} {% block head_extra %} {% endblock %} {% block layout %} {% with messages = get_flashed_messages(with_categories=true) %} {% if messages %}
{% for category, message in messages %}
{{ message }}
{% endfor %}
{% endif %} {% endwith %}
{% if banner_html %}
{{ banner_html | safe }}
{% endif %}
Getting started

Install the {{ instance_brand or "Agnes" }} CLI on this machine

Connect your terminal and Claude Code to this server. Copy the one-liner below — it downloads and installs the CLI wheel, then seeds your local config.

{{ server_url }} {% if agnes_version and agnes_version != "dev" %} v{{ agnes_version }} {% endif %}
1 Quick install
{% if session.user %}

One click generates a personal access token, assembles a complete setup script (install CLI, save token, verify), and copies it to your clipboard. Paste the result into Claude Code to finish.

Valid 90 days · token stays in your clipboard only.

What Claude Code will receive

Read-only preview. The real token is generated when you click the button above and is placed directly in your clipboard — it is never rendered on this page.

{% with preview_mode=True %} {% include "_claude_setup_instructions.jinja" %} {% endwith %}
Or run manually on a restricted environment
$ curl -fsSL {{ server_url }}/cli/install.sh | bash

If agnes is not found in a new shell, add ~/.local/bin to your PATH:

$ export PATH="$HOME/.local/bin:$PATH"

Add that line to your ~/.bashrc or ~/.zshrc for persistence.

{% else %}

Run this in your terminal (Linux / macOS). The installer downloads the wheel and seeds ~/.config/agnes/config.yaml with this server URL.

Sign in to skip the manual steps — you'll get a one-click setup with a pre-configured token.

$ curl -fsSL {{ server_url }}/cli/install.sh | bash

If agnes is not found in a new shell, add ~/.local/bin to your PATH:

$ export PATH="$HOME/.local/bin:$PATH"

Add that line to your ~/.bashrc or ~/.zshrc for persistence.

{% endif %}
{% if not session.user %}
You'll need to sign in first to create a personal access token. Sign in →
{% endif %}
2 Create a personal access token

Tokens let the CLI, CI jobs, and Claude Code talk to the server without a browser session.

Open /me/profile#tokens
After generating your token

Export it for the current shell and verify the connection:

$ export AGNES_TOKEN=<your-token>
$ agnes auth whoami
Manual install For restricted environments, offline machines, or Windows — download the wheel yourself.
  1. Download the wheel from {{ server_url }}/cli/download.
  2. Install it:
    $ uv tool install ./agnes_the_ai_analyst-*.whl
    — or —
    $ python3 -m pip install --user ./agnes_the_ai_analyst-*.whl

    On macOS (Homebrew) or recent Debian/Ubuntu, pip install --user is blocked by PEP 668 — prefer uv tool install above. The pip command is for users with an activated virtualenv.

    If agnes is not found after install, ensure ~/.local/bin is on your PATH:

    $ export PATH="$HOME/.local/bin:$PATH"

    Add that line to your ~/.bashrc or ~/.zshrc to make it persistent.

  3. Seed the server URL:
    $ mkdir -p ~/.config/agnes && echo "server: {{ server_url }}" > ~/.config/agnes/config.yaml
  4. Continue with Step 2 — Create a personal access token above.
Running in CI or a headless environment? Read the headless usage guide →
{% endblock %} {% block scripts %} {% endblock %}