Sandbox Connector Specs

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:

~/.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.

{
  "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:

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

It also writes a command shim:

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

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

{
  "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 ↗.

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.