Docs

Optimal Engine quickstart

This guide runs one Engine on your machine, creates a workspace, stores a source, and finds it again. It takes about ten minutes, most of it the first compile. To use a managed Engine on MIOSA instead, skip to On MIOSA.

You end with:

  • an Engine on http://127.0.0.1:4200;
  • an API key that scopes every request;
  • a workspace default:notes with one stored source;
  • a search result that points back to that source.

1. Run the Engine

2. Check that it answers

In a second terminal:

export OPTIMAL_ENGINE_API_KEY="<your key>"
curl -s http://127.0.0.1:4200/api/health -H "Authorization: Bearer $OPTIMAL_ENGINE_API_KEY"
{
  "status": "up",
  "live": true,
  "checks": {
    "store": ":ok",
    "migrations": ":ok",
    "credential_key": ":ok",
    "network_auth": ":ok"
  },
  "degraded": [],
  "warnings": []
}

status is up, degraded when there is a warning, or down when a check fails. The real response also carries the release identity.

3. Create a workspace

curl -s -X POST http://127.0.0.1:4200/api/workspaces 
  -H "Authorization: Bearer $OPTIMAL_ENGINE_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"slug": "notes", "name": "Notes"}'

The response is the new workspace. Its id is default:notes; use that id everywhere below.

4. Store a source

curl -s -X POST http://127.0.0.1:4200/api/ingest 
  -H "Authorization: Bearer $OPTIMAL_ENGINE_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "workspace": "default:notes",
    "title": "Supplier renewal call",
    "text": "Renewal call with the supplier moved to the 14th. The contract review is still open."
  }'
{
  "ok": true,
  "signal_id": "...",
  "genre": "...",
  "type": "...",
  "entities": [],
  "source_package_id": "..."
}

The Engine kept the source, classified it, and proposed claims from it. A claim becomes a fact once it is reviewed or meets the workspace’s promotion rule; see Concepts.

5. Search and ask

curl -s "http://127.0.0.1:4200/api/search?q=supplier%20renewal&workspace=default:notes&limit=5" 
  -H "Authorization: Bearer $OPTIMAL_ENGINE_API_KEY"

Each result has a title, the matching content, a score, and a uri in the optimal:// scheme that points back to the source.

curl -s -X POST http://127.0.0.1:4200/api/rag 
  -H "Authorization: Bearer $OPTIMAL_ENGINE_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"query": "What is open with the supplier?", "workspace": "default:notes", "format": "markdown"}'

envelope.body is the context an answer should be written from, and envelope.sources lists the sources it used. The Engine does not write the answer itself; hand the envelope to your model or agent.

6. Use the client CLI

The repository ships a small client CLI, optimal (also called oe), that needs only sh, curl, and awk.

apps/cli/install.sh
export OPTIMAL_ENGINE_URL=http://127.0.0.1:4200
optimal doctor
optimal search "supplier renewal" -w default:notes

See CLI, SDKs and MCP for every command and for connecting an agent over MCP.

On MIOSA

Managed Engines are enabled per organization. Once yours is enabled:

  1. Open Optimal > Memory in the console and pick a workspace.
  2. Press Start Memory. The console shows the size and the hourly price before it creates anything.
  3. When Memory is running, search it on the same page, or ask Optimal in a chat to save a note to Memory.

From a terminal, the MIOSA CLI does the same:

miosa engine create notes-brain --workspace notes --for workspace --wait
miosa engine connect notes-brain
optimal search "supplier renewal"

See Optimal Engine on MIOSA for what is included and how to ask for access.

Was this page helpful?