Attachments, size limits and media generation

You can give the agent images, PDFs, audio and video, and it can read such files in your project. What works depends on the model. This page lists what each provider accepts, the size limits, and how to let the agent generate images and video.

Attach a file

Where	How
Terminal UI	Drag a file into the terminal or paste its path; it becomes a chip
Desktop	Attach files, or drop files on the chat
One prompt	`haarness run -f photo.png -f spec.pdf "…"`
API and SDKs	`attachments` on the turn; the SDKs' `attachments()` helper reads local files

The agent can also open media files in your project with its read tool. They reach the model the same way as an attachment.

What each provider accepts

Provider	Images	PDF	Audio	Video
OpenAI	Yes	Yes	No	No
Anthropic	Yes	Yes	No	No
Amazon Bedrock	Yes	Yes	No	No
Gemini and Vertex AI	Yes	Yes	Yes	Yes
Azure, Copilot and OpenAI-compatible	If the model supports them	Yes	MP3, WAV	No

The model has the last word: an attachment it cannot use returns an error that says so. For audio and video, use a Gemini model.

For a custom or local provider, images are off until you set "images": true, because Haarness cannot tell whether the model accepts them.

Size limits

Limit	Applies to
20 MiB in total	The attachments on one message
10 MiB in total	The attachments on one message to Gemini or Vertex AI
20 MiB	One media file the agent reads; see execution budgets
10 MiB	One file opened or saved in Desktop's file explorer
50 MiB	One generated image or video

Desktop also accepts at most 20 files per message.

When you are attached to a server on another machine, the files you attach are uploaded with your message, so the server does not need access to your disk.

When a chat gets too long

Every model has a context window. When a chat fills most of it, Haarness summarises the older part and keeps the recent turns word for word, so you can carry on. Type /compact in the terminal UI to do it now.

You can turn this off or change when it happens with the compaction settings in Configuration. Haarness takes each model's context and output size from the provider, or from its own catalogue when the provider does not say. For a custom provider, set context_window and max_output_tokens yourself.

Generate images and video

The agent can create an image or a video when you ask for one. Generation is off until you configure a backend:

Tool	Turn it on with
Images	`OPENAI_API_KEY` in the environment (uses OpenAI's image API), or `HAARNESS_IMAGE_GENERATE_URL`
Video	`HAARNESS_VIDEO_GENERATE_URL`

A stored OpenAI key or a ChatGPT sign-in does not turn on image generation; the environment variable does. Set it before Haarness starts its server.

Each generation asks for your permission first, because it costs money and writes a file, unless your permission rules already allow it ("media_generate": "allow"). In a chat in Auto, Auto's reviewer answers that request instead of you. The result is saved in .haarness-chat-attachments/ in your project, which Haarness keeps out of Git, and shown in the chat.

Use your own generation service

Point HAARNESS_IMAGE_GENERATE_URL or HAARNESS_VIDEO_GENERATE_URL at an HTTPS endpoint (http://localhost also works). Haarness sends a JSON POST with model and prompt, plus size for images or aspect_ratio and duration for video. If HAARNESS_MEDIA_API_KEY is set, it goes in an Authorization: Bearer header; your OpenAI key is never sent there.

Reply with JSON containing the base64 file in b64_json, base64 or data, and optionally its type in mime_type. Haarness checks that the bytes are really an image or video.