Sandbox connector specs are the machine-readable contract Aileron uses to expose installed connector operations inside sandboxed launch sessions.

When a connector package is installed, Aileron looks for:

```text
~/.aileron/store/connectors/sha256/<hash>/aileron.connector.v1.json
```

At launch time, Aileron reads those installed specs, renders `/etc/aileron/tools.txt`, and mounts generated command shims under `/usr/local/bin`. The shims are HTTPS clients that call the local Aileron daemon through `AILERON_API_URL`.

## Schema

The current schema version is `aileron.connector.v1`.

```json
{
  "schema_version": "aileron.connector.v1",
  "connector": {
    "fqn": "github://acme/aileron-connector-google",
    "version": "1.2.3"
  },
  "tools": [
    {
      "name": "google",
      "description": "Google APIs",
      "operations": [
        {
          "name": "gmail.messages.search",
          "summary": "Search Gmail messages",
          "method": "GET",
          "path": "/gmail/v1/users/me/messages",
          "hosts": ["gmail.googleapis.com"],
          "idempotency": "idempotent",
          "credential": "oauth2",
          "inputs": [
            {
              "name": "q",
              "type": "string",
              "required": false,
              "description": "Gmail search query"
            }
          ]
        }
      ]
    }
  ]
}
```

Required fields:

| Field | Requirement |
|---|---|
| `schema_version` | Must be `aileron.connector.v1`. |
| `connector.fqn` | Must be a valid connector FQN. |
| `tools[].name` | Must be unique within the spec and use only letters, digits, dots, dashes, underscores, or colons. |
| `tools[].operations[]` | Each tool must declare at least one operation. |
| `operations[].name` | Must be unique within its tool and use only letters, digits, dots, dashes, underscores, or colons. |
| `operations[].hosts[]` | Required for proxy transport. Each entry is an allowed upstream host, with an optional port, and must not include a URL scheme or path. |
| `operations[].inputs[].name` | Optional, but when present must be unique within the operation and use the same restricted character set. |
| `operations[].audit[].name` | Optional, but when present must be unique within the operation and use the same restricted character set. |

Optional operation metadata such as `summary`, `description`, `method`, `path`, `hosts`, `idempotency`, `approval`, `credential`, `inputs`, and `audit` is rendered into shim help and is available to the data-plane work that follows.

## Generated Tools

For each tool, launch writes one `tools.txt` entry:

```text
google  github://acme/aileron-connector-google -- Aileron connector operations: gmail.messages.search
```

It also writes a command shim:

```bash
google --help
google gmail.messages.search --args '{"q":"from:[email protected]"}' --json
```

The shim posts this payload to `${AILERON_API_URL%/}/connector-operations/run`:

```json
{
  "connector_fqn": "github://acme/aileron-connector-google",
  "tool": "google",
  "operation": "gmail.messages.search",
  "args": {
    "q": "from:[email protected]"
  }
}
```

The endpoint is the stable sandbox-side contract for generated connector-operation shims.

In the current daemon cut, `/v1/connector-operations/run` resolves the connector, tool, and operation against installed specs. `GET`, `DELETE`, and `HEAD` operations with spec-declared method, path, and upstream hosts are mediated through the sandbox HTTPS proxy boundary with shim args encoded as query parameters. `POST`, `PATCH`, and `PUT` operations send shim args upstream as an `application/json` request body. The proxy boundary resolves any spec-declared credential binding in the daemon, injects supported credentials at the upstream request boundary, returns a sanitized response, and audits `connector.proxy.proxied` without credential bytes, query strings, or request body values. Unknown connector operations are rejected before any execution attempt. Full forward-proxy integration for arbitrary HTTPS clients remains tracked in [#896](https://github.com/ALRubinger/aileron/issues/896).

## Conflict Handling

Sandbox launch fails with an actionable error when:

- two installed connector specs resolve to the same tool command
- a connector spec tool command conflicts with an installed action shim
- a connector spec tool command conflicts with the selected agent command, such as `claude`

Installed action shims still come from action manifests. Spec-backed shims do not replace action dispatch; they add the connector-operation contract needed for direct, typed operations.