Connections

A Connection allows communication with a specified external host and can store credentials for its API. Wings adds authentication when it connects, so you do not put keys in Handler code. A Handler cannot read the credentials stored in a Connection.

Every external fetch() requires a matching Connection bound to the Handler or Run. Hosts without a Connection are blocked, including public pages, RSS feeds, and public APIs.

Connect a public host without authentication

Use --auth none when a host does not require credentials:

wings connection add status-claude --host status.claude.com --auth none

No token or clipboard access is needed. This Connection stores no credentials and adds no authentication headers. It allows only the exact host status.claude.com, not subdomains or other hosts. Wildcards and suffix matching are not supported for unauthenticated Connections, so they cannot expand access beyond the host you chose. Private IP addresses and internal hosts remain blocked; external requests use HTTPS on port 443. Redirects must remain on the same origin and within the selected Connection's host policy.

Save this as status.js and bind the Connection when running it:

export default async function () {
  const response = await fetch('https://status.claude.com/api/v2/status.json', {
    agiWings: { connection: 'status' },
  })
  if (!response.ok) throw new Error('Status request failed')
  return response.json()
}

wings run --file status.js --connection status=status-claude
wings handler deploy --name status-check --file status.js --connection status=status-claude

In the Console's Connection page, use the form for adding a Connection without authentication and enter its name and host. Then assign it to the Handler's Connection settings. The authenticated API accepts the same host-only configuration:

POST /api/v1/wings/connections
Content-Type: application/json

{"name":"status-claude","host":"status.claude.com","authType":"none"}

Omit credential, credentials, authParam, provider, preset, and config; they are rejected with authType: "none". To replace an old dummy-header Connection, use the same name and add --replace. This removes its stored credentials and preserves existing Handler bindings.

1. Connect GitHub

Copy a token with access to the GitHub API to your clipboard, then run:

wings connection add github-main --host api.github.com --auth bearer

The CLI does not display the token.

2. Save the code

Save this as github-issues.js. It reads your GitHub issues and returns their count.

export default async function () {
  const response = await fetch('https://api.github.com/issues', {
    headers: { 'User-Agent': 'wings-digest' },
    agiWings: { connection: 'github' },
  })
  if (!response.ok) throw new Error('GitHub request failed')
  const issues = await response.json()
  return { count: issues.length }
}

3. Deploy and check it

wings handler deploy --name github-issues --file github-issues.js --connection github=github-main
wings handler list

Run the Handler using the ID from the list:

wings run <handler-id>
wings handler logs <handler-id>

You should see a count and a successful Run. If authentication fails, check your GitHub token and its read permissions.

Choose which Connection a Handler uses

A saved Handler can use only the Connections specified when you deploy it. In --connection github=github-main, the left side is the name used in code. The right side is the Connection's registered name. Renaming a Connection does not break Handlers already using it.

A custom Connection matches only the exact hostname you specify. A Connection for api.example.com does not cover its subdomains. Choose none, bearer, or header:<name> authentication. If multiple bound Connections match one host, select one with agiWings.connection; Wings never falls back to another Connection's credentials.

Connect with a preset

Slack, Cloudflare, freee OAuth, and Google OAuth connect through the browser. For Google OAuth, add --client-credentials to use your own OAuth client.

Discord, Google service accounts, Webull, and X OAuth 1.0a read credentials from the clipboard. See the Connection commands for preset syntax.

Rename or remove a Connection

wings connection list
wings connection rename github-main github-work
wings connection remove github-work

Replacing an existing Connection requires --replace. Presets using an OAuth client provided by Wings do not support this flag. Remove and reconnect them instead. After removing a Connection or changing its permissions, check the Handlers that use it.