---
title: Titan Harness quickstart
description: Apply an agent, price a task, run it, follow it live and download
  its files, with the Hexel CLI, the TypeScript SDK or the Python SDK.
url: https://hexelstudio.com/docs/harness/quickstart
---

This guide applies an agent that writes a short report in its sandbox, prices a task for it, runs the task, follows it live and downloads the report.

You need an organization in the [private preview](https://hexelstudio.com/docs/harness/access), and the workspace and environment Hexel Studio set up for the harness.

<Tabs>
  <Tab title="CLI">
    <Steps>
      <Step title="Install the CLI and sign in">
        Install `hexel` 0.10.0 or later ([Install and sign in](https://hexelstudio.com/docs/cli/overview)), sign in and select the workspace and environment:

        ```bash
        hexel auth login
        hexel context set --workspace ws_456 --env env_789
        ```
      </Step>
      <Step title="Apply an agent">
        An agent is a spec bundle in YAML or JSON. Save this as `reporter.yaml`:

        ```yaml reporter.yaml
        name: reporter
        model: anthropic/claude-sonnet-5-5
        instructions: Use the shell to gather facts, write report.md and export it with export_file.
        tools: [shell, write_file, export_file]
        ```

        Apply it and point its `prod` channel at the new version:

        ```bash
        hexel harness agent apply reporter.yaml --promote prod
        ```
      </Step>
      <Step title="Price the task">
        The estimate prices a task the way creating it would, and starts or charges nothing:

        ```bash
        hexel harness task estimate --agent reporter@prod --max-estimate-usd 5
        ```

        It shows the estimated cost, whether it is within your ceiling, and whether billing would admit the task.
      </Step>
      <Step title="Create the task and follow it">
        ```bash
        hexel harness task create "Write a short report of the sandbox OS version" \
          --agent reporter@prod --budget-usd 2 --max-estimate-usd 5
        ```

        The command prints the task's id (`tsk_...`). Follow it live until it ends:

        ```bash
        hexel harness tail -f tsk_123
        ```

        You see the agent's messages, tool calls and results, questions, approvals and cost. Add `--follow` to `task create` to start following at once.
      </Step>
      <Step title="Download the report">
        ```bash
        hexel harness artifacts list tsk_123
        hexel harness artifacts pull tsk_123 --dir ./out
        ```

        `pull` gets a short-lived link to each file in your organization's storage and checks each file's SHA-256 before it saves it.
      </Step>
    </Steps>
  </Tab>
  <Tab title="TypeScript">
    <Steps>
      <Step title="Install the SDK">
        During the private preview, `@hexelstudio/titan-harness` is published privately to GitHub Packages. Ask Hexel Studio for access, then point the `@hexelstudio` scope at GitHub Packages with a GitHub token that has the `read:packages` scope:

        ```ini .npmrc
        @hexelstudio:registry=https://npm.pkg.github.com
        //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
        ```

        ```bash
        npm install @hexelstudio/titan-harness
        ```

        It needs Node 20 or later and has no dependencies.
      </Step>
      <Step title="Create a client">
        `defaultCredentials()` takes the first token it finds: `HEXEL_TOKEN`, workload identity, `HEXEL_API_KEY`, then the `hexel` CLI's login.

        ```ts
        import { Harness } from "@hexelstudio/titan-harness"
        import { defaultCredentials } from "@hexelstudio/titan-harness/credentials"

        const h = new Harness({ token: defaultCredentials(), workspace: "ws_456", environment: "env_789" })
        ```
      </Step>
      <Step title="Apply, price, run and follow">
        ```ts
        await h.agents.apply(
          {
            name: "reporter",
            model: "anthropic/claude-sonnet-5-5",
            instructions: "Use the shell to gather facts, write report.md and export it with export_file.",
            tools: ["shell", "write_file", "export_file"],
          },
          { promote: "prod" },
        )

        const estimate = await h.estimates.task({ agent: "reporter@prod", maxEstimateUsd: 5 })
        console.log(estimate.usd, estimate.within_budget, estimate.admitted)

        const task = await h.tasks.create("Write a short report of the sandbox OS version", {
          agent: "reporter@prod",
          maxUsd: 2,
          maxEstimateUsd: 5,
        })
        for await (const ev of h.tasks.events(task.id)) {
          if (ev.type === "message.delta") process.stdout.write(String(ev.data.text))
        }
        await h.tasks.wait(task.id) // throws TaskFailed unless the task succeeded
        ```
      </Step>
      <Step title="Download the report">
        ```ts
        import { createHash } from "node:crypto"
        import { writeFile } from "node:fs/promises"

        for (const a of await h.tasks.artifacts(task.id)) {
          const link = await h.tasks.artifactLink(task.id, a.id)
          const res = await fetch(link.url, { method: link.method, headers: link.headers })
          const bytes = Buffer.from(await res.arrayBuffer())
          if (createHash("sha256").update(bytes).digest("hex") !== link.content_sha256) throw new Error("checksum mismatch")
          await writeFile(a.name || a.id, bytes)
        }
        ```
      </Step>
    </Steps>
  </Tab>
  <Tab title="Python">
    <Steps>
      <Step title="Install the SDK">
        During the private preview, `hexel-titan-harness` is distributed privately as a wheel. Ask Hexel Studio for access, then install the wheel you receive:

        ```bash
        pip install ./hexel_titan_harness-0.1.0-py3-none-any.whl
        ```

        It needs Python 3.10 or later. The import name is `titan_harness`.
      </Step>
      <Step title="Create a client">
        With no arguments the client reads `HEXEL_WORKSPACE` and `HEXEL_ENV`, and takes the first token it finds: `HEXEL_TOKEN`, workload identity, `HEXEL_API_KEY`, then the `hexel` CLI's login.

        ```python
        from titan_harness import Harness

        h = Harness(workspace="ws_456", environment="env_789")
        ```
      </Step>
      <Step title="Apply, price, run and follow">
        ```python
        h.agents.apply(
            {
                "name": "reporter",
                "model": "anthropic/claude-sonnet-5-5",
                "instructions": "Use the shell to gather facts, write report.md and export it with export_file.",
                "tools": ["shell", "write_file", "export_file"],
            },
            promote="prod",
        )

        estimate = h.estimates.task(agent="reporter@prod", max_estimate_usd=5)
        print(estimate["usd"], estimate["within_budget"], estimate["admitted"])

        task = h.tasks.create(
            "Write a short report of the sandbox OS version",
            agent="reporter@prod", max_usd=2, max_estimate_usd=5,
        )
        for ev in h.tasks.events(task.id):
            if ev.type == "message.delta":
                print(ev.data["text"], end="", flush=True)

        done = h.tasks.wait(task.id)  # raises TaskFailed unless the task succeeded
        ```

        `AsyncHarness` has the same calls as coroutines.
      </Step>
      <Step title="Download the report">
        ```python
        import hashlib
        import urllib.request

        for a in h.tasks.artifacts(task.id):
            link = h.tasks.artifact_link(task.id, a["id"])
            req = urllib.request.Request(link["url"], method=link["method"], headers=link.get("headers") or {})
            data = urllib.request.urlopen(req).read()
            assert hashlib.sha256(data).hexdigest() == link["content_sha256"]
            open(a["name"] or a["id"], "wb").write(data)
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## If the task is refused

| Error | What to do |
| --- | --- |
| `403 org_not_in_preview` | Your organization is not in the private preview yet. See [Private preview access](https://hexelstudio.com/docs/harness/access). |
| `403 harness_not_in_plan` | The Titan Harness add-on is not on your plan. |
| `402 insufficient_balance` | Top up your balance in the console. |
| `422 estimate_over_budget` | The estimate is above `max_estimate_usd`. Raise the ceiling or lower the work. |
| `429 too_many_running_tasks` | Your organization has as many tasks queued, running or waiting as it may. See [Limits and pricing](https://hexelstudio.com/docs/harness/limits-and-pricing). |

## Next steps

- [Agents and versions](https://hexelstudio.com/docs/harness/agents): channels, canaries and rollback.
- [Tasks and runs](https://hexelstudio.com/docs/harness/tasks): steer a task, answer its questions, pause and resume it.
- [Approvals and autonomy](https://hexelstudio.com/docs/harness/approvals): decide what the agent may do without asking.
