---
title: Quickstart
description: Sign in, connect a GitHub repository and run your first Ysra session — from the portal, the mobile app or the API.
status: new
---

This guide takes you from a new account to a verified candidate on a repository
you own. It takes about five minutes, plus however long your test suite runs.

!!! info "Before you start"
    You need a Ysra account and admin access to a GitHub repository, so you can
    install the Ysra GitHub App on it.

## Run your first session

<div class="steps" markdown>

### Sign in

=== "Portal"

    Open the portal and sign in with your email and password. The first screen
    is **What should Ysra build?**

=== "API"

    Exchange your credentials for a bearer token. Tokens last 24 hours by
    default.

    ```console
    $ curl -sS "$YSRA_API_URL/auth/login" \
        -H 'content-type: application/json' \
        -d '{"email": "you@example.com", "password": "…"}'
    {"access_token": "eyJhbGciOi…", "token_type": "bearer", "user": {…}}
    ```

    Export it for the rest of this guide:

    ```console
    $ export YSRA_TOKEN="eyJhbGciOi…"
    ```

### Connect a repository

Install the **Ysra GitHub App** on the repository from your workspace settings.
Access is scoped to the workspace: Ysra sees only the repositories you grant.

Ysra then gets to know the repository without running any of its code: the
language and frameworks, and the commands your project already uses to install,
test, type-check, build and preview.

### Check what is enabled

Capabilities vary by account and deployment. Read them before relying on a
behaviour — the portal does the same before it renders any control.

```console
$ curl -sS "$YSRA_API_URL/developer/account/capabilities" \
    -H "authorization: Bearer $YSRA_TOKEN"
```

### Start a session

Describe the outcome, not the steps. Name the repository and set a budget; the
session stops and asks before it would exceed it.

> Fix the flaky `test_parse_iso_week` test and make date parsing accept ISO
> week dates like `2026-W39-5`.

Ysra compiles the goal into acceptance criteria, starts work on an isolated
candidate and streams its progress. You can steer it, answer its questions or
interrupt at any point.

### Review and deliver

When the session finishes, review the **diff**, the **checks** it ran and the
**report**. What happens next depends on your
[autonomy policy](../workspace/autonomy-policy.md): by default the candidate is
preserved for you to deliver, and you choose **Open PR** when you are satisfied.

</div>

## What to read next

- [How sessions work](../developer/index.md) — states, checkpoints and steering.
- [Verification](../developer/review.md) — what "verified" means, precisely.
- [API overview](../api/index.md) — conventions every client should follow.