# Quickstart

## Install

Finn runs on [Agentica](https://github.com/agentica-lang/agentica) 0.34.0 or later: `agentica` on your `PATH`, or `AGENTICA` set to the binary.

1. Clone the repository: `git clone https://github.com/agentica-lang/agc-agent`.
2. In the clone, run `make install`. It fetches the packages that the server and the TUI depend on.
3. Use `bin/finn` from any folder, or link it into your `PATH`: `ln -s "$PWD/bin/finn" ~/.local/bin/finn`.

`finn --version` prints the versions of the server and the client.

## Set up a provider

Out of the box, Finn talks to a llama.cpp `llama-server` at `http://127.0.0.1:8080/v1`. For any other provider, give it a key:

```sh
finn login              # pick a provider, then paste its key
finn login anthropic    # or name the provider
```

Finn checks the key with one call to the provider, then stores it for the next starts. A key in the environment works too, and wins over a stored one: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `FIREWORKS_API_KEY`, `GROQ_API_KEY` or `DEEPSEEK_API_KEY`. See [Providers](https://www.agentica-lang.com/agc-agent/providers/index.md).

On the first start, `finn` opens the login list itself when there is no key file, no key of a provider in the environment, and none of `FINN_BASE_URL`, `FINN_PROVIDER` and `FINN_API` is set. Close it with no key and it is not offered again: `/login` sets up a provider later. After a login, a session on `local` gets the models of the provider just set up in a list: Enter moves the session to the one picked, from the next turn, and Esc keeps it on `local`.

## The first session

Go to the folder of your project and start a client:

```sh
cd ~/src/my-project
finn            # the full screen (finn tui is the same)
finn chat       # or the line-mode client
```

The client starts the server when none runs, and leaves it running when you quit. Type a task and press Enter. The model answers, and shows each tool call it makes: the files it reads and edits, the commands it runs.

Some things to try:

- `/model` lists the models of your providers; `/model anthropic/NAME` picks one.
- `@` then part of a name completes a file path of the folder in your message (`finn`).
- `!git status` runs the command and gives its output to the model with your next message.
- `/resume` lists your sessions and switches to one.
- Esc (`finn`) or Ctrl+C (`finn chat`) stops the running turn ([Stop](https://www.agentica-lang.com/agc-agent/cli/index.md#stop)).

The rest is on [CLI and TUI](https://www.agentica-lang.com/agc-agent/cli/index.md).

## One task, then exit

```sh
finn -p "fix the failing test"
echo "explain this repo" | finn -p -
```

The answer goes to stdout and the rest to stderr ([One task](https://www.agentica-lang.com/agc-agent/cli/index.md#one-task)).

## Before you trust it with a folder

The approvals are off by default: the model runs commands and edits files without asking. Run Finn in a sandbox or a container, or turn the approvals on ([Approvals and security](https://www.agentica-lang.com/agc-agent/security/index.md)).
