> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent-mintlify-f21cea86.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Running the autonomous goal agent

> Use Arka's goal agent to run autonomous multi-step terminal tasks — set up environments, debug, refactor, and run tests with step budgets and security gates.

The goal agent runs multi-step tasks autonomously: set up environments, debug, refactor, and run tests with a step budget and security gates.

## Usage

```bash theme={null}
arka goal set up a venv, install requests, and run pytest
arka goal -y -n 30 debug why nginx fails
arka goal --butterfish refactor this module and run tests
```

From zsh/bash (no fish required):

```bash theme={null}
arka goal debug my nginx setup
arka goal -b -y set up venv and run pytest
```

## Engines

| Engine | Behavior |
| - | - |
| `auto` / `arka` | Built-in goal agent (default) |
| `butterfish` | Launches Butterfish shell (`!goal`) |
| `legacy` | Original JSON loop only |
| `off` | Disables goal delegation |

```env theme={null}
GOAL_ENGINE=auto
GOAL_MAX_STEPS=25
GOAL_AUTO_CONTINUE=1
GOAL_OUTPUT_LIMIT=8000
```

## How it works

The goal agent uses a Butterfish-style run/fix loop with shell history, file reads, and security gates. Each step can invoke any registered skill or safe shell command.

Use `-y` to auto-confirm risky steps only when you trust the environment.

## Related

* `agent_plan` — upfront JSON planning (separate from reactive goal loop)
* `arka loop` — alias for `arka goal` when `GOAL_ENGINE=auto`


## Related topics

- [How to code with Arka](/guides/code-with-arka.md)
- [Self-improve loop](/guides/self-improve.md)
- [Security model and prompt-injection defenses](/concepts/security.md)
- [Arka CLI command and flag reference](/guides/cli.md)
- [Operation modes](/guides/operation-modes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.