# Your first task

This page takes you from connecting GitHub to a draft pull request. To try
Cloud Agents without a repository, [start from scratch](from-scratch.md)
instead; it needs no GitHub connection.

## Before you start

- **Agent access.** Cloud Agents are enabled per account during the beta.
- **A GitHub repository you can push to.** The result is a branch and a pull
  request in that repository.
- **Daily quota.** The agent's model calls count toward your account's daily
  usage quota, like your other API traffic.

## 1. Connect GitHub

1. Open [https://agents.freeinference.org](https://agents.freeinference.org)
   (also linked as **Agents** from the FreeInference dashboard) and sign in
   with your FreeInference account.
2. Choose **Connect GitHub**, either from **Getting started** in the sidebar or
   from **My Settings → Integrations**, and approve the sign-in on GitHub.
3. Install the FreeInference GitHub App on your account or an organization,
   and select which repositories it may access.

Back on the Agents page, the repository picker lists the repositories the App
can access and you can push to. To add more later, choose **Configure
repository access** at the bottom of the picker, or **Configure repositories**
on the Integrations page, then **Refresh** the picker.

To start in a new repository, choose **Create new repository** in the picker.
It is created in your personal GitHub account, private unless you choose
**Public**, with a README so it has a branch to start from. If the App does
not have access to it yet, give it access and refresh.

To disconnect, choose **Manage → Disconnect GitHub** on the Integrations page.
That removes your stored GitHub authorization. Uninstalling the App in your
GitHub settings is what removes its access to your repositories.

## 2. Describe the task

In the composer:

1. Describe the change the way you would brief a colleague: what to change,
   where, and how to tell it is done. For example: *"Fix the SSE total-timeout
   regression on /v1/messages and add a unit test that reproduces it."*
2. Pick the **Repository** and the **Branch** to start from.
3. Pick the **Agent**, the **Model** and, where offered, the **Reasoning**
   level — see [Agents and models](models.md).
4. Choose **Run**, or press **Enter**. **Shift+Enter** adds a new line.

Cloud agents do best on self-contained changes: a bug fix with a clear
description, a focused refactor, tests for an under-covered module, a
documentation sweep. Put conventions the agent should always follow, such as
how to run the tests, in your repository's `AGENTS.md` or `CLAUDE.md`, or save
them as [memory](tools.md#memory).

Keep these limits in mind:

- **One repository per task**, and **GitHub only**. GitLab is not supported
  yet.
- **Dependencies install over HTTPS.** `pip install`, `npm ci` and Git over
  HTTPS work. The agent runs as an unprivileged user, so `apt install` does
  not; use a virtualenv or `pip --user`. Other ports, including Git over SSH,
  are blocked.
- **Each turn has a time limit** of one hour.

The **+** menu in the composer attaches files, sets a goal, and picks the
skills, MCP servers, SSH servers, plugins and environment for the task — see
[Working in a task](tasks.md#the-composer).

## 3. Watch it work

The first turn takes longer: the platform creates the conversation's sandbox
and clones the repository into it. The agent keeps going if you close the page,
and a blue dot appears beside the task when it finishes.

The task page streams the agent's work as it happens. **Chat** shows its
replies with compact tool calls; **Trajectory** shows every step with its
input and output. If the agent asks you a question, a dialog opens and the turn
waits for your answer. Under each finished turn, **Recorded changes** lists the
files it changed.

## 4. Create the pull request

When you are happy with the changes, choose **Create PR**. The platform checks
the changes, pushes them to an `agent/…` branch in your repository and opens a
draft pull request, linked from the task. Your CI runs on that branch as on
any other, if your workflows are set up that way.

Want changes? Reply in the same conversation. When the new turn finishes,
**Update PR** pushes its changes to the same pull request. Merging stays with
you.

## Next steps

- [Working in a task](tasks.md) — follow-ups, queued messages, stopping,
  goals, forks, and reviewing the pull request
- [Environments](environments.md) — install dependencies and start services
  before every task
- [Sandbox and security](security.md) — what the agent can reach and what gets
  published