Custom providers

Hosted Salambo agents can use declarative custom providers, including models outside the built-in catalogue. Custom providers work in hosted deployments only: local salambo dev refuses them, including CLIProxyAPI.

When deploy refuses a model

The deploy preflight checks a built-in model against the server's model catalogue before upload. If the model has been removed from Salambo's model library, the refusal names it, says nothing was uploaded, and suggests choosing another model in your settings file, for example the template model openai/gpt-5.2, or declaring the model yourself as a custom provider. It names no successor model. A declaration does not make a nonexistent model endpoint work.

Declared custom providers are not refused because their model is absent from the built-in catalogue. Agents with extensions are also exempt from that early refusal, because their registrations are only known at Turn time. The exemption is not proof that a model will run: provider configuration and authentication still have to succeed when the Turn starts.

Declare the endpoint and model

Use .salambo/settings.json:

{
  "defaultProvider": "company-gateway",
  "defaultModel": "support-v1",
  "defaultThinkingLevel": "off",
  "providers": {
    "company-gateway": {
      "name": "Company gateway",
      "baseUrl": "https://gateway.example.com/v1",
      "apiKeyEnv": "GATEWAY_API_KEY",
      "models": [
        {
          "id": "support-v1",
          "name": "Support model",
          "api": "openai-completions",
          "reasoning": false,
          "input": ["text"],
          "cost": {
            "input": 1,
            "output": 3,
            "cacheRead": 0,
            "cacheWrite": 0
          },
          "contextWindow": 32000,
          "maxTokens": 4096
        }
      ]
    }
  }
}

The endpoint, model limits and cost values above are illustrative, not a live service or a Salambo price. Replace them with the real provider's values. Supported API adapters are openai-completions, openai-responses and anthropic-messages.

baseUrl must use public HTTPS, without credentials, query, fragment or a non-default port. The CLI refuses IP literals and internal names; server validation and destination authorization still apply. Provider IDs and model IDs must be unique. A model may instead declare inherits: { provider, modelId } plus supported overrides; inheritance still needs a valid source model.

Supply a host-scoped runtime secret

A complete minimal salambo.yaml for that settings file:

version: 1
name: support-agent
image:
  mode: managed
agent:
  name: Support Agent
  slug: support-agent
  isActive: true
runtimeConfig:
  sandboxRegion: eu
  egressPolicyMode: restricted
  egressAllowlist: []
  workspaceUpgradePolicy: automatic
env: {}
secrets:
  GATEWAY_API_KEY:
    fromEnv: GATEWAY_API_KEY
    exposeTo:
      - runtime
    allowedHosts:
      - gateway.example.com

Set the key in your deployment environment. The secret needs runtime exposure and a host scope that permits the provider's host; sandbox-only exposure is not enough. A declared provider does not hand the plaintext key to extension code or sandbox tools. A key managed in the dashboard must meet the same rules.

Register from an extension

Hosted extensions can call agent.registerProvider(id, config) while the factory registers. This is declarative registration, not provider code: native provider objects, executable stream callbacks and OAuth implementations are not accepted. Use a complete model definition and an environment reference such as $GATEWAY_API_KEY, never a raw key. The permissive ProviderConfig type does not mean every value it allows is valid at runtime.

Settings declarations are the simpler starting point. salambo dev refuses both settings-based providers and the registration APIs.

Verify in phases

salambo manifest --path . --json
salambo doctor
salambo deploy
salambo smoke "Reply with a short greeting."

A valid manifest proves the declaration's shape, not DNS, endpoint reachability, provider credentials or model availability. A hosted smoke test proves those against the selected deployment.