Connect your application to private AI.

Choose an integration path

Both paths use the same application token, worker network, routing, and execution history. Choose based on the contract your application needs.

Quickstart

Create an account and application in the console, then copy the application token when it is shown. AI Hub stores only its digest, so the plaintext token cannot be recovered later.

AI_HUB_URL=https://your-hub.example \
AI_HUB_WORKER_TOKEN=aih_... \
AI_MODEL_URL=http://127.0.0.1:8080/v1 \
AI_MODEL=local-model \
bundle exec ruby worker/worker.rb

Configure AI Hub through your agent

Connect to the remote MCP server with scoped browser authorization. OAuth PKCE identifies the AI Hub user, agent, organization, and approved management capabilities. Application keys remain separate runtime credentials and are not needed in MCP configuration.

Codex CLI

codex mcp add ai-hub \
  --url https://aihub.mohsal.dev/mcp \
  --oauth-resource https://aihub.mohsal.dev/mcp

codex mcp login ai-hub --oauth-client-registration dcr

Claude Code CLI

claude mcp add --transport http --scope user \
  ai-hub https://aihub.mohsal.dev/mcp

claude mcp login ai-hub

{
  "mcpServers": {
    "ai-hub": {
      "url": "https://your-hub.example/mcp"
    }
  }
}

Available tools

Organization owners can inspect agents, scopes, grant expiry, denials, and immutable activity—or restrict an agent to selected applications and revoke its grant immediately—from Agents & audit. Each application's Settings screen also provides application-level agent access controls.

See the complete MCP authorization and tool reference.

Make calibrated decisions with Laya

A typed decision evaluates an input state against questions stored in the task definition. Questions cannot be replaced by the calling application, which makes the decision contract stable, auditable, and safe to reuse.

1. Publish the immutable questions

Create the task once from the console or API. The input schema validates each submitted state; the executor configuration defines the questions the Laya worker will ask.

curl -X POST https://your-hub.example/api/v1/task_definitions \
  -H 'Authorization: Bearer aih_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "task_definition": {
      "key": "support.route",
      "version": 1,
      "executor": "typed_decision",
      "instructions": "Route incoming support requests.",
      "input_schema": {
        "type": "object",
        "additionalProperties": false,
        "required": ["message"],
        "properties": { "message": { "type": "string" } }
      },
      "executor_config": {
        "questions": {
          "department": {
            "type": "choice",
            "instructions": "Which team should handle this request?",
            "criteria": {
              "billing": "Payments, invoices, charges, or refunds",
              "technical": "Product errors or technical help",
              "other": "Anything else"
            }
          }
        }
      }
    }
  }'

2. Evaluate synchronously

The client supplies only the state being evaluated. AI Hub waits for the durable job to finish and returns the typed answers directly. Send an Idempotency-Key so a retry returns the same decision.

curl -X POST https://your-hub.example/api/v1/typed-decisions/support.route@1/evaluate \
  -H 'Authorization: Bearer aih_...' \
  -H 'Idempotency-Key: ticket-4821-route-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "input": {
      "message": "Please refund the duplicate charge on my card."
    }
  }'

{
  "id": "job_...",
  "status": "completed",
  "task": "support.route@1",
  "decisions": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": {
        "billing": 0.94,
        "technical": 0.03,
        "other": 0.03
      }
    }
  },
  "usage": {
    "input_tokens": 51,
    "output_tokens": 0,
    "total_tokens": 51
  }
}

3. Use a durable job when you do not want to wait

The native job endpoint returns immediately. Put the idempotency key in the request body and poll the returned job.

curl -X POST https://your-hub.example/api/v1/jobs \
  -H 'Authorization: Bearer aih_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "task": "support.route@1",
    "idempotency_key": "ticket-4821-route-v1",
    "input": {
      "message": "Please refund the duplicate charge on my card."
    }
  }'

4. Poll for the durable result

A submitted job moves from queued to leased, then to completed. Poll the returned job ID until it reaches a terminal state.

curl https://your-hub.example/api/v1/jobs/job_... \
  -H 'Authorization: Bearer aih_...'

{
  "id": "job_...",
  "status": "completed",
  "task": "support.route@1",
  "output": {
    "answers": {
      "department": {
        "type": "choice",
        "choice": "billing",
        "probabilities": {
          "billing": 0.94,
          "technical": 0.03,
          "other": 0.03
        }
      }
    }
  }
}

Give chat models a stable contract

A model profile is an immutable chat_completion definition. Its key and version become the public model ID, such as assistant.general@1. The profile controls system instructions; the worker’s AI_MODEL selects the underlying model.

Use the SDK you already know

Use the application token as the API key and append /v1 to the Hub origin.

from openai import OpenAI

client = OpenAI(
    api_key="aih_...",
    base_url="https://your-hub.example/v1",
)

response = client.responses.create(
    model="assistant.general@1",
    input="Summarize this report",
)
print(response.output_text)

Available endpoints

Run longer work in the background

Set background: true when work may outlive one HTTP request. The create call returns a durable job ID immediately.

curl -X POST https://your-hub.example/v1/responses \
  -H 'Authorization: Bearer aih_...' \
  -H 'Content-Type: application/json' \
  -d '{"model":"assistant.general@1","input":"Write a brief","background":true}'

curl https://your-hub.example/v1/responses/job_... \
  -H 'Authorization: Bearer aih_...'

Run durable, schema-validated jobs

Use native jobs for structured output, retries, idempotency, explicit versions, and asynchronous execution.

Job lifecycle

Retryable failures and expired leases return a job to the queue until its attempt budget is exhausted. Permanent failures end in failed; exhausted jobs end in dead.

Keep models private and outbound-only

Workers advertise executor capabilities and claim only compatible jobs. The official worker creates an Ed25519 device key on first boot and enrolls its public identity with a one-time owner-issued grant.

Read the identity protocol, threat model, and Laya MLX setup.

Meter every execution attempt

Every claim creates a separate execution record, including retries. Workers report bounded token counts, model identity, and inference duration. AI Hub measures elapsed Hub time and finalizes every record once.

Current limits

• OpenAI surfaceText inputs and outputs only; no streaming, tools, images, files, audio, or embeddings yet.
• Payload sizeNative job inputs and results are limited to 256 KiB.
• SQLiteRun one Hub replica and keep all database files on durable storage.
• SecretsUse HTTPS and keep application and worker tokens in a secret manager.

For the full wire contract and operational details, see the OpenAI integration guide and protocol reference.