opencode/packages/www/content/docs/(Configure)/attachments.mdx

---
title: "Attachments"
---

Attachments add local context to a prompt as text or image media. Regardless
of how a prompt is submitted, current V2 sessions make these attachment types
visible to the model:

| Input                   | Model receives                                                 |
| ----------------------- | -------------------------------------------------------------- |
| UTF-8 text file         | The filename and decoded text                                  |
| Directory               | A non-recursive listing of its immediate files and directories |
| PNG, JPEG, GIF, or WebP | Image media                                                    |

SVG files are treated as text, not image media. PDF, AVIF, BMP, audio, video,
and other binary prompt attachments are not currently included in the model
request. A client accepting a file does not mean its contents are visible to
the model.

<Callout type="warning">
  Use a model that supports image input before attaching an image. OpenCode passes supported image media to the selected
  provider, but the provider and model still enforce their own formats, dimensions, file counts, and size limits. A
  text-only model may reject the request.
</Callout>

## Add attachments

Desktop and web clients provide **Attach file**, paste, and drag-and-drop controls for supported text and image files. The
desktop file picker limits one selection to 20 MiB in total; the server also applies the per-attachment limit below.

Attachment controls and client-side limits depend on the interface. For programmatic submission, see the generated
[API reference](/api).

V2 prompt and command inputs represent each attachment with a `uri` and
optional `name` and `description`. Use an absolute `file:` URL for a file or
directory available to the server, or an inline `data:` URL. For a text `file:`
URL, optional positive `start` and `end` query parameters select one-based
lines:

```text
file:///home/me/project/src/server.ts?start=20&end=60
```

HTTP and HTTPS attachment URLs are not supported. OpenCode materializes each
attachment before admitting the prompt and rejects invalid URLs, unreadable
paths, non-files other than directories, and attachments over 20 MiB decoded.
The server infers the media type from the bytes. A supplied filename or data
URL media type does not make an unsupported binary format model-visible.

## Configure image processing

Configure image normalization in `opencode.json` or `opencode.jsonc`:

```jsonc title="opencode.jsonc"
{
  "$schema": "https://opencode.ai/config.json",
  "media": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880,
    },
  },
}
```

All fields are optional:

| Field              |   Default | Behavior                                                                            |
| ------------------ | --------: | ----------------------------------------------------------------------------------- |
| `auto_resize`      |    `true` | Resize an image that exceeds any configured limit. If `false`, reject it.           |
| `max_width`        |    `2000` | Maximum width in pixels. Must be a positive integer.                                |
| `max_height`       |    `2000` | Maximum height in pixels. Must be a positive integer.                               |
| `max_base64_bytes` | `5242880` | Maximum byte length of the Base64-encoded image string. Must be a positive integer. |

<Callout type="note">
  These settings apply to supported image media attached directly to prompts and images produced by the built-in `read`
  tool. If the image resizer is unavailable, OpenCode passes the original image through unchanged.
</Callout>

The `read` tool recognizes PNG, JPEG, GIF, and WebP by their contents and will
ingest at most 20 MiB of source image bytes. It decodes the image and compares
its width, height, and encoded Base64 length with all three configured limits.

When `auto_resize` is `true`, OpenCode preserves the aspect ratio, scales the
image down to the dimension limits, and tries progressively smaller PNG and
JPEG encodings until the Base64 limit is met. The resulting media type can
therefore change to PNG or JPEG. If no encoding fits, the tool call fails.

When `auto_resize` is `false`, exceeding any limit fails the tool call without
modifying the image. An image that cannot be decoded also fails. If the image resizer cannot be loaded, OpenCode uses the
original image instead, so these settings are processing limits rather than an upload or security boundary.

## Limits and provider behavior

- Direct prompt attachments are limited to 20 MiB decoded per item by the V2
  server. Client-specific limits can be lower.
- `max_base64_bytes` counts the encoded Base64 characters in bytes, not the
  decoded file size and not the complete `data:` URL.
- Text attachments are inserted into the prompt as text and do not require a
  multimodal model. Large text read through the `read` tool has separate
  paging and truncation limits.
- Image attachments use provider-native image input. Provider errors can still
  occur when OpenCode's limits pass but the selected model's limits do not.
- PDFs and other unsupported binary prompt attachments should be converted to
  text or supported images before attaching them.