Decidealot

Your hardware. Local decision models. Run Laya, Von, or a CLM projection head through TypeSafe-compatible HTTP or MCP.

At startup Decidealot downloads and verifies every enabled local bundle. It then loads only the provider selected by a request, unloads it after the configured idle period, and returns typed choice, score, and noul answers with model probabilities. CLM adds a small local projection head over one configured Qwen3-8B embeddings endpoint. It exposes the TypeSafe HTTP API and MCP Streamable HTTP from the same local container.

Contents

• Quick start
• Use the API
• Use MCP
• Expose MCP through a proxy
• Pick a model
• Configuration
• CUDA
• Model storage and unloading
• Agent integrations
• Docs

Quick start

You need Docker. This starts the CPU image on loopback, stores downloaded model files in one narrow host directory, and gives the container no capabilities or writable root filesystem.

model_directory="$HOME/.local/share/decidealot/models"
runtime_uid=$(id -u)
runtime_gid=$(id -g)
mkdir --parents "$model_directory"

docker run --detach --name decidealot --init --restart unless-stopped \
  --user "$runtime_uid:$runtime_gid" \
  --read-only --cap-drop ALL --security-opt no-new-privileges:true \
  --pids-limit 512 --memory 8g --cpus 4 \
  --tmpfs /tmp:rw,noexec,nosuid,size=128m \
  --tmpfs /var/run:rw,noexec,nosuid,size=8m \
  --log-driver json-file --log-opt max-size=10m --log-opt max-file=5 \
  --mount type=bind,source="$model_directory",target=/models \
  --publish 127.0.0.1:8080:8080 \
  psyb0t/decidealot:latest

Check the service, then ask Laya to make one typed decision:

curl --fail http://127.0.0.1:8080/health

curl --fail http://127.0.0.1:8080/v1/systemone \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "laya",
    "state": "A proposed action would permanently delete protected data.",
    "questions": {
      "handling": {
        "type": "choice",
        "instructions": "Choose the required handling for this action.",
        "criteria": {
          "allow": "The action is reversible and does not affect protected data.",
          "require_review": "The action is irreversible or affects protected data."
        }
      }
    }
  }'

The first service startup downloads the enabled pinned model bundles and can take several minutes. The default configuration enables Laya and Von. Wait for /health before sending a decision. Later service starts reuse the same host directory. The response includes answers.handling.choice and a probability per choice key. Your caller chooses what to do with that decision, for example only allowing allow when its probability meets your own threshold.

Use the API

Send the state to judge and a bounded question. Decidealot returns typed results with probabilities.

| Endpoint | What it does | | --- | --- | | POST /v1/systemone | Runs the selected model against state and returns typed answers. | | GET /v1/models | Lists every supported alias and the model behind it. | | POST /v1/models/unload | Stops all providers. | | /mcp | Version 2 MCP Streamable HTTP, with system_one, list_models, and unload_models tools. | | GET /health | Reports whether downloaded model bundles are ready. |

choice questions need named criteria. score questions need an ordered criteria array whose position is the score. noul questions return a probability between zero and one. The API guide has the request rules, response shape, validation failures, aliases, authentication, and lifecycle behavior.

Use MCP

The same container serves MCP Streamable HTTP at http://127.0.0.1:8080/mcp. The system_one tool takes the same model, state, and questions fields as POST /v1/systemone. list_models returns the live catalog. unload_models releases local model memory. Direct loopback clients and containers using the decidealot Docker service name work by default.

Point an MCP client at that exact URL. Its configuration format varies, but the connection values are always equivalent to this:

{
  "mcpServers": {
    "decidealot": {
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

Omit the Authorization header only when DECIDEALOT_API_KEY is empty. The MCP tools return structured output matching the HTTP result bodies, so an agent can inspect probabilities before it chooses the next action. A client that only supports local stdio can use the optional OpenClaw bridge described in Agent integrations. The API guide has tool inputs, output shapes, session behavior, and failure behavior.

Expose MCP through a proxy

The MCP server keeps DNS-rebinding protection enabled. A proxy, tunnel, or public DNS name must be allowed explicitly. Add the exact public Host value to DECIDEALOT_MCP_ALLOWED_HOSTS. Browser-based MCP clients must also add their exact origin, including the scheme, to DECIDEALOT_MCP_ALLOWED_ORIGINS.

For a proxy that publishes https://mcp.example.net/mcp, put these values in the Compose .env file before docker compose up -d, or pass the same variables with docker run --env:

DECIDEALOT_API_KEY=repl…[redacted]
DECIDEALOT_MCP_ALLOWED_HOSTS=127.0.0.1,127.0.0.1:*,localhost,localhost:*,[::1],[::1]:*,decidealot,decidealot:*,mcp.example.net
DECIDEALOT_MCP_ALLOWED_ORIGINS=http://127.0.0.1:*,http://localhost:*,http://[::1]:*,https://mcp.example.net

Keep --publish 127.0.0.1:8080:8080 when a local reverse proxy terminates TLS. The proxy forwards the request unchanged with Host: mcp.example.net. After bearer authentication, Decidealot returns 421 for an untrusted host and 403 for an untrusted browser origin. Invalid or missing bearer credentials return 401 first. Do not disable this protection or allow a broad wildcard for an internet-facing endpoint.

Pick a model

Every request must name a selector. GET /v1/models returns the same catalog at runtime.

| Selector | What it runs | Pick it when | | --- | --- | --- | | laya, laya-auto, laya-latest | Laya with automatic checkpoint routing. | State may arrive in more than one language or script. | | laya-english | Laya's English checkpoint. | State is English and uses the Latin script. | | laya-multilingual | Laya's multilingual checkpoint. | State is in another language or script, including short Latin-script text that is not clearly English. | | laya-typed-decisions | Laya's checkpoint tuned for structured workflow decisions. | Your workload looks like repeated policy, routing, triage, or approval decisions. Validate it on your own cases first. | | von, von-latest, von-1.1, von-1.1.0 | The local English-only Von 1.1 model. | You want Von's independent result for a short, well-posed decision, or want to compare it with Laya before standardizing a workflow. | | clm, clm-latest, clm-0.1, clm-0.1-8b | The local CLM v0.1 projection head over one configured Qwen3-8B embeddings endpoint. | You have a trusted embeddings service that emits CLM-compatible 4096-wide last-token Qwen3-8B vectors. |

What differs

Laya is one model family with three checkpoints. Its automatic selectors choose English or multilingual checkpoints from the input script and a language heuristic. Use laya-multilingual for known non-English short Latin-script messages. laya-typed-decisions targets repeated structured decision work.

Von is a separate English-only decision model for short questions with clear criteria. CLM is a local 75 MB projection head, not a text encoder. It calls one configured OpenAI-compatible /v1/embeddings URL and requires its configured model to return Qwen3-8B last-token vectors with exactly 4096 float values. All providers take the same TypeSafe state and questions shape and return typed choice, score, and noul answers with probabilities. Your application applies the threshold and action that follow.

Decidealot keeps one provider resident. Moving between Laya selectors stays in the Laya provider. Moving to another provider waits for active work, releases the old model, Torch allocations, and CUDA context, then starts the requested one.

Set DECIDEALOT_PROVIDER_IDLE_UNLOAD_SECONDS to choose when an idle provider releases its model and Torch memory.

Configuration

Pass configuration with --env-file or your container manager. The image uses fixed internal ports. Docker port publishing controls where the service is reachable.

| Variable | Default | Meaning | | --- | --- | --- | | DECIDEALOT_API_KEY | empty | Optional Bearer token for every public API and MCP request. | | DECIDEALOT_MAX_REQUEST_BYTES | 1048576 | Maximum JSON request body size. | | DECIDEALOT_PROVIDER_IDLE_UNLOAD_SECONDS | 600 | Idle time before automatic unload. Set 0 to disable only timeout-based unloads. | | DECIDEALOT_LAYA_ENABLED | true | Download and expose Laya selectors. | | DECIDEALOT_VON_ENABLED | true | Download and expose Von selectors. | | DECIDEALOT_CLM_ENABLED | auto | Enable CLM when its embeddings URL is set. Use true to require it or false to skip it. | | DECIDEALOT_CLM_EMBEDDINGS_URL | empty | Exact OpenAI-compatible /v1/embeddings URL used only by CLM. Required when CLM is enabled. | | DECIDEALOT_CLM_EMBEDDINGS_MODEL | qwen3-8b | Model selector sent to the embeddings endpoint. It must produce Qwen3-8B last-token vectors with width 4096. | | DECIDEALOT_CLM_EMBEDDINGS_API_KEY | empty | Optional Bearer token sent only to the configured CLM embeddings endpoint. | | DECIDEALOT_CLM_EMBEDDINGS_TIMEOUT_SECONDS | 120 | One CLM embeddings request timeout in seconds. | | DECIDEALOT_MCP_ALLOWED_HOSTS | loopback names and decidealot | Comma-separated Host values accepted by MCP. Add each reverse-proxy hostname here. | | DECIDEALOT_MCP_ALLOWED_ORIGINS | loopback HTTP origins | Comma-separated browser origins accepted by MCP. Add each public browser origin here. |

The container always stores bundles under /models. Its only model storage setting is the host directory mounted there. To run only CLM, set DECIDEALOT_LAYA_ENABLED=false, DECIDEALOT_VON_ENABLED=false, and configure DECIDEALOT_CLM_EMBEDDINGS_URL. The upstream endpoint receives your decision state and criteria, so use an endpoint you control or trust. Keep the loopback bind for one-host use. Before putting Decidealot behind a proxy, tunnel, or public address, set DECIDEALOT_API_KEY to a real secret, require Authorization: Bearer <your-key> from every caller, and configure the precise MCP host and origin allowlists above.

CUDA

psyb0t/decidealot:latest-cuda uses CUDA 12.6 and needs a compatible NVIDIA driver, NVIDIA Container Toolkit, and --gpus all. CUDA images are amd64-only. The CPU image is the right default unless inference speed and model memory justify the GPU setup.

model_directory="${model_directory:-$HOME/.local/share/decidealot/models}"
runtime_uid=$