Skip to content
Hexel StudioDocs

Titan Harness quickstart

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.

On this page

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, and the workspace and environment Hexel Studio set up for the harness.

  1. Install the CLI and sign in

    Install hexel 0.10.0 or later (Install and sign in), sign in and select the workspace and environment:

    Bash
    hexel auth login
    hexel context set --workspace ws_456 --env env_789
  2. Apply an agent

    An agent is a spec bundle in YAML or JSON. Save this as reporter.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
  3. 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.

  4. 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.

  5. 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.

If the task is refused

ErrorWhat to do
403 org_not_in_previewYour organization is not in the private preview yet. See Private preview access.
403 harness_not_in_planThe Titan Harness add-on is not on your plan.
402 insufficient_balanceTop up your balance in the console.
422 estimate_over_budgetThe estimate is above max_estimate_usd. Raise the ceiling or lower the work.
429 too_many_running_tasksYour organization has as many tasks queued, running or waiting as it may. See Limits and pricing.

Next steps