Quickstart

From nothing to a streamed turn in five steps. Commands are shown as olxcore api ... (the core's command line); an olx api alias is coming.

1. Enable the API

It is off by default. Only the owner can turn it on, from the Mac's terminal.

olxcore api on

developer API: on (start it with `olxcore api serve`)

Start the gateway. It binds 127.0.0.1:8780 (and refuses any non-loopback address) and prints one line when it is listening:

olxcore api serve

2. Create a token for your app

Tokens are created by the owner, one per app, with the scopes it needs. --allow-dir grants a project folder; without it a turn runs in the app's own empty workspace folder. The secret is shown once; only its hash is stored.

olxcore api token create my-app --scopes chat,models --allow-dir ~/Projects/demo

{"app":"my-app","id":"c5f3020e","scopes":["chat","models"],"dirs":["/tmp/olix-demo/project"],"token":"olxk_c5f3020e_XXXX","note":"shown once; only a hash is stored"}

3. Check the connection

curl -s http://127.0.0.1:8780/v1/status \
  -H "Authorization: Bearer $OLIX_API_TOKEN"

{"api":"v1","app":"sample-app","scopes":["chat","models"],"core":{"reachable":true,"protocol":"olix.codeui/1","active_turns":0},"turns_running":0}

4. Run a turn

With "stream": false the call waits and returns the outcome:

curl -s http://127.0.0.1:8780/v1/turns \
  -H "Authorization: Bearer $OLIX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Say hello in five words.", "cwd": "/tmp/olix-demo/project", "stream": false}' | jq '{outcome, text, session_id}'

{
  "outcome": "answered",
  "text": "stand-in reply to: Say hello in five words.",
  "session_id": "20261106132214-80194c"
}

By default the response is Server-Sent Events, one event per core event, ending at task_complete:

curl -sN http://127.0.0.1:8780/v1/turns \
  -H "Authorization: Bearer $OLIX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Say hello in five words.", "cwd": "/tmp/olix-demo/project"}'

event: accepted
data: {"protocol":"olix.codeui/1","type":"accepted","request_id":"t_abd196b48cf83e93","session_id":"20261106132214-54f2e5"}

event: memory_used
data: {"fact_ids":[],"style":["length"],"ms":0.3,"protocol":"olix.codeui/1","type":"memory_used","session_id":"20261106132214-54f2e5","request_id":"t_abd196b48cf83e93","seq":0,"ts":1793971334.525,"epoch":"cdca17e5-d15b-4dee-b565-34a7f275e474","session_seq":1}

event: assistant_start
data: {"protocol":"olix.codeui/1","type":"assistant_start","session_id":"20261106132214-54f2e5","request_id":"t_abd196b48cf83e93","seq":1,"ts":1793971334.537,"epoch":"cdca17e5-d15b-4dee-b565-34a7f275e474","session_seq":2}

event: assistant_delta
data: {"text":"stand-in reply to: Say hello in five words.","protocol":"olix.codeui/1","type":"assistant_delta","session_id":"20261106132214-54f2e5","request_id":"t_abd196b48cf83e93","seq":2,"ts":1793971334.537,"epoch":"cdca17e5-d15b-4dee-b565-34a7f275e474","session_seq":3}

event: assistant_end
data: {"text":"stand-in reply to: Say hello in five words.","protocol":"olix.codeui/1","type":"assistant_end","session_id":"20261106132214-54f2e5","request_id":"t_abd196b48cf83e93","seq":3,"ts":1793971334.537,"epoch":"cdca17e5-d15b-4dee-b565-34a7f275e474","session_seq":4}

event: usage
data: {"prompt_tokens":5,"cached_tokens":0,"output_tokens":1,"tok_s":0,"context_pct":0,"ttft_ms":1,"pass_id":"call_mw507ouf2","model":"olx-1","kind":"chat","protocol":"olix.codeui/1","type":"usage","session_id":"20261106132214-54f2e5","request_id":"t_abd196b48cf83e93","seq":4,"ts":1793971334.537,"epoch":"cdca17e5-d15b-4dee-b565-34a7f275e474","session_seq":5}

event: task_complete
data: {"outcome":"answered","text":"stand-in reply to: Say hello in five words.","result":{"state":"completed","answer":"stand-in reply to: Say hello in five words.","summary":"stand-in reply to: Say hello in five words."},"protocol":"olix.codeui/1","type":"task_complete","session_id":"20261106132214-54f2e5","request_id":"t_abd196b48cf83e93","seq":5,"ts":1793971334.549,"epoch":"cdca17e5-d15b-4dee-b565-34a7f275e474","session_seq":6}

Continue the conversation by sending the returned session_id with the next turn. Every event is documented under Events.

5. Use an SDK, or the OpenAI SDK

Node (version 20 or newer):

node sdk/examples/quickstart.mjs

status: {"api":"v1","app":"sample-app","scopes":["chat","models"],"core":{"reachable":true,"protocol":"olix.codeui/1","active_turns":0},"turns_running":0}
stand-in reply to: Say hello in five words.
[answered]

Python:

python3 sdk/examples/quickstart.py

status: {'api': 'v1', 'app': 'sample-app', 'scopes': ['chat', 'models'], 'core': {'reachable': True, 'protocol': 'olix.codeui/1', 'active_turns': 0}, 'turns_running': 0}
stand-in reply to: Say hello in five words.
[answered]

The OpenAI-compatible endpoint needs only the models scope. Point the official openai package at the gateway:

"""The official OpenAI SDK pointed at the local gateway. Needs a token with the `models` scope."""
import os
from openai import OpenAI

client = OpenAI(base_url=os.environ.get("OLIX_API_URL", "http://127.0.0.1:8780") + "/v1", api_key=os.environ["OLIX_API_TOKEN"])
r = client.chat.completions.create(model="blink 1.1", messages=[{"role": "user", "content": "Name a colour."}])
print(r.choices[0].message.content)

stand-in completion for: Name a colour.

Stop it

olxcore api off

This flips the switch and stops a running gateway; a gateway that sees the switch off stops by itself within a second. olxcore api token revoke my-app ends one app's access at once, including open socket connections.

When something needs the owner

If a turn wants to run something that changes a file or the system, olix raises an approval card for the owner, and your stream receives it as a read-only question event. You can deny it or wait; you cannot approve it. See Safety.