Tutorial Title — From Zero to Enterprise AI Agents
Description: Tutorial description goes here.

Tutorial 01

# Getting Started — Your First AI Coding Agent

In this tutorial you will install Harness, configure your first provider, and run an AI coding agent against a real codebase in under ten minutes. No prior agent experience required.

## Introduction

Harness is an open-source coding agent that runs entirely from your terminal. Unlike GUI-based tools, every behaviour is scriptable, auditable, and embeddable in your existing CI/CD pipelines. This template demonstrates every reusable component available in the tutorial series.

The inline code component renders like this: `harness run --task "fix all linting errors"`. Use it for short commands or identifiers inside body text.

## Prerequisites

- Python 3.11 or later
- `uv` package manager installed
- An API key for Anthropic, OpenAI, Google, or a local Ollama instance

## Code Blocks

Code blocks support a language badge, an optional filename, and a copy-to-clipboard button.

Bash

    uv tool install harness-agent
    harness --version

Python agent.py

    import asyncio
    import harness

    async def main():
        async for message in harness.run(
            "Refactor utils.py to use type hints",
            provider="anthropic",
            model="claude-sonnet-4-20250514",
            permission_mode="accept_edits",
        ):
            match message:
                case harness.TextMessage(text=t, is_partial=False):
                    print(t)
                case harness.ToolUse(name=name):
                    print(f"  Tool: {name}")
                case harness.Result() as r:
                    print(f"Done: {r.turns} turns, ${r.total_cost:.4f}")

    asyncio.run(main())

TOML ~/.harness/config.toml

    [provider]
    name    = "anthropic"
    model   = "claude-opus-4-6"
    api_key = "sk-ant-..."

    [budget]
    max_tokens = 50000
    max_cost   = 1.00   # USD

    [permissions]
    mode = "accept_edits"

## Provider Tabs

The tab component lets readers select their AI provider. Each tab panel contains provider-specific instructions.

### Tab Usage

Set your Anthropic API key as an environment variable:

Bash

    export ANTHROPIC_API_KEY="sk-ant-..."
    harness init --provider anthropic --model claude-opus-4-6

Set your OpenAI API key as an environment variable:

Bash

    export OPENAI_API_KEY="sk-..."
    harness init --provider openai --model gpt-4o

Set your Google AI API key as an environment variable:

Bash

    export GOOGLE_API_KEY="AIza..."
    harness init --provider google --model gemini-2.0-flash

Run Ollama locally, then point Harness at your local endpoint. No API key required.

Bash

    ollama pull llama3.3
    harness init --provider ollama --model llama3.3 --base-url http://localhost:11434

## Callout Boxes

ℹ️

Info

Harness stores its configuration at `~/.harness/config.toml` with permissions set to `0o600` so only your user account can read it.

⚠️

Warning

Never commit your `config.toml` file to version control. Add it to your `.gitignore` before running `git init`.

✅

Success

If you see Agent initialised in the terminal output, Harness has successfully connected to your provider and is ready to accept tasks.

❌

Error

A `401 Unauthorized` response means your API key is invalid or has expired. Regenerate the key in your provider's dashboard and update `config.toml`.

🚀

Try It

Open your terminal right now and run `harness run --task "list all TODO comments in this repo"` inside any project. The agent will scan your code and produce a structured report in seconds.

## Collapsible Sections

Use collapsibles for optional deep-dives, advanced configuration, or troubleshooting details that would otherwise break reading flow.

Harness loads its system prompt from `~/.harness/system_prompt.md` if the file exists. You can override any default instruction by adding your own directives to this file.

The agent uses an action-oriented prompt by design: it should never ask clarifying questions when running in bypass mode. To enforce stricter guardrails, use `mode = "supervised"` in your config instead.

If Harness times out when connecting to your provider, check your network proxy settings. Set `HTTPS_PROXY` in your environment and restart the agent.

You can also increase the default request timeout by adding `timeout = 120` (seconds) to the `[provider]` section of your config.

## Step Indicators

Use numbered steps for installation flows, setup wizards, or any process that must be followed in sequence.

1

Install Harness via uv

The recommended installation method is via the `uv` tool manager, which places the `harness` binary in `~/.local/bin/`.

Bash

    uv tool install harness-agent

2

Initialise your configuration

Run the interactive setup wizard to create `~/.harness/config.toml` with your chosen provider and model.

Bash

    harness init

3

Run your first task

Navigate to any project directory and issue a task in plain English. Harness will plan, execute, and summarise the changes it made.

Bash

    cd ~/my-project
    harness run --task "Add type hints to all functions in src/"

## Competitor Comparison

See how Harness stacks up against other popular AI coding agents across the enterprise features that matter most.

### What competitors can't do

14 enterprise features exclusive to Harness or unavailable in competing tools

Feature | Harness | Claude Code | Cursor | Aider | OpenHands | SWE-Agent
--- | --- | --- | --- | --- | --- | ---
Multi-provider (5+) | ✓ | ✗ | ✗ | ✓ | ✓ | ✗
Full async SDK | ✓ | ✗ | ✗ | ✗ | ✓ | ✗
4-mode permissions | ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Token/cost budgets | ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Policy-as-code | ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Audit hash chain | ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Dual sandbox modes | ✓ | ✗ | ✗ | ✗ | ✓ | ✓
Sub-agent parallelism | ✓ | ✓ | ✗ | ✗ | ✗ | ✗
Native CI/CD | ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Model router + fallback | ✓ | ✗ | ✗ | ✗ | ✗ | ✗
PII scanning | ✓ | ✗ | ✗ | ✗ | ✗ | ✗
OpenTelemetry | ✓ | ✗ | ✗ | ✗ | ✗ | ✗
Hooks system | ✓ | ✓ | ✗ | ✗ | ✗ | ✗
REPL with slash cmds | ✓ | ✓ | ✗ | ✗ | ✗ | ✗