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.
- Install the CLI and sign in
Install
hexel0.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 - 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
prodchannel at the new version:Bash hexel harness agent apply reporter.yaml --promote prod - 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 5It shows the estimated cost, whether it is within your ceiling, and whether billing would admit the task.
- 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 5The command prints the task's id (
tsk_...). Follow it live until it ends:Bash hexel harness tail -f tsk_123You see the agent's messages, tool calls and results, questions, approvals and cost. Add
--followtotask createto start following at once. - Download the report
Bash hexel harness artifacts list tsk_123 hexel harness artifacts pull tsk_123 --dir ./outpullgets a short-lived link to each file in your organization's storage and checks each file's SHA-256 before it saves it.
- Install the SDK
During the private preview,
@hexelstudio/titan-harnessis published privately to GitHub Packages. Ask Hexel Studio for access, then point the@hexelstudioscope at GitHub Packages with a GitHub token that has theread:packagesscope:.npmrc @hexelstudio:registry=https://npm.pkg.github.com //npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}Bash npm install @hexelstudio/titan-harnessIt needs Node 20 or later and has no dependencies.
- Create a client
defaultCredentials()takes the first token it finds:HEXEL_TOKEN, workload identity,HEXEL_API_KEY, then thehexelCLI's login.TypeScript 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" }) - Apply, price, run and follow
TypeScript 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 - Download the report
TypeScript 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) }
- Install the SDK
During the private preview,
hexel-titan-harnessis 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.whlIt needs Python 3.10 or later. The import name is
titan_harness. - Create a client
With no arguments the client reads
HEXEL_WORKSPACEandHEXEL_ENV, and takes the first token it finds:HEXEL_TOKEN, workload identity,HEXEL_API_KEY, then thehexelCLI's login.Python from titan_harness import Harness h = Harness(workspace="ws_456", environment="env_789") - 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 succeededAsyncHarnesshas the same calls as coroutines. - 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)
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. |
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. |
Next steps
- Agents and versions: channels, canaries and rollback.
- Tasks and runs: steer a task, answer its questions, pause and resume it.
- Approvals and autonomy: decide what the agent may do without asking.