---
canonical: "https://agi-labo.com/en/tools/wings/docs/handlers-runs"
title: "Handlers and Runs"
description: "Understand saved code, individual executions, updates, and file input."
section: "Core features"
order: 4
pageType: "concept"
lastVerifiedVersion: "1.4.16"
lastVerifiedAt: "2026-10-15"
draft: false
surfaces: ["cli", "console", "api"]
plans: ["free", "member"]
---

A Handler is saved JavaScript; a Run is one execution.
You can also run code without saving a Handler by using `wings run --file handler.js`.

Ordinary Handlers use `export default async function (event, env)`.
[Web Apps](/en/tools/wings/docs/web-apps) use `fetch(request, env)`.

## Allow external hosts

Every external `fetch()` requires a matching Connection bound to the Handler or Run.
Public pages, RSS feeds, and public APIs follow the same rule.
For a host without authentication, run `wings connection add status-claude --host status.claude.com --auth none`, then add `--connection status=status-claude` to `wings run --file handler.js` or `wings handler deploy`.
Use `agiWings: { connection: 'status' }` in the fetch options to select it.
See [Connections](/en/tools/wings/docs/connections) for exact host matching and setup in the Console or API.

## Update a Handler

```sh
wings handler deploy --update <handler-id> --file handler.js
```

An update keeps the ID, Triggers, Secrets, Database, and history.
Omitting `--connection` also keeps the existing Connection settings.
Supplying it replaces the entire set of Connection settings.
You cannot use `--schedule` with an update.

## Remove a Handler

```sh
wings handler rm <handler-id>
```

Removing a Handler also removes its Triggers, Secrets, and links to Connections.
You can no longer read its past Runs with `logs` or `run show`.
Save any results you need first.

## Pass a file

```sh
wings run <handler-id> --input ./input.bin
```

The Handler receives the file through `await env.input()`.
You can read the returned Response's content only once.

- Input must be one regular file, up to 1 GiB.
- It is sent in chunks of up to 8 MiB.
- An account can have one prepared or active input at a time.
- Input is not stored. It is discarded on completion, cancellation, or expiry.

## Transfer large data to an external API

Add `agiWings: { stream: true }` to an external fetch to stream the transfer.
Requests can be up to 100 MiB, and responses up to 1 GiB.
Without this option, the limits are 1 MiB for requests and 4 MiB for responses.

The external service's limits still apply.
Streaming does not extend the 30-second / 120-second Run deadline.
Wings does not automatically resend a stream because data already sent may have triggered an external action.

See [Run duration](/en/tools/wings/docs/run-duration) and [History and logs](/en/tools/wings/docs/history-logs).