Sandbox Connector Specs

Sandbox connector specs are the machine-readable contract Aileron uses to validate and mediate connector operations inside sandboxed launch sessions.

When a connector package is installed, Aileron looks for:

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

At launch time, Aileron reads those installed specs and derives the connector tools and operations the daemon uses to validate requests on the HTTPS data plane. The agent reaches connector operations through aileron-mcp (ADR-0024), which is the sole in-container tool surface; the generated tools.txt/shim surface was retired in #959 ↗.

Schema

The current schema version is aileron.connector.v1.

{
  "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 carried into the derived operation help the daemon uses for data-plane validation.

Data-Plane Operation Contract

The daemon resolves connector operations against installed specs at the /v1/connector-operations/run data-plane endpoint. A request names the connector, tool, and operation, and carries the operation args:

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

GET, DELETE, and HEAD operations with spec-declared method, path, and upstream hosts are mediated through the sandbox HTTPS proxy boundary with args encoded as query parameters. POST, PATCH, and PUT operations send 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 ↗.

Conflict Handling

Spec loading fails with an actionable error when two installed connector specs resolve to the same tool name. The tool-name sanitizer normalizes each tools[].name before the comparison, so two specs whose names normalize to the same value are reported as a conflict.