First-Run Setup

The first time you run oasis-agent in a terminal with no endpoint configured, it asks one question instead of failing on a missing flag. The answer is saved, so it is asked once.

# Run it again later to change any of it
oasis-agent setup

The question

Three answers.

Answer	For
Magnum AI, from mutexer	Private cloud inference on dedicated hardware, built for industrial code generation. Nothing is metered per token and your code stays on your hardware
Self-hosted	Any OpenAI-compatible server you run: ollama, vLLM, llama.cpp, LM Studio
Checks only	A machine with no model server yet. Runs 33 conformance checks against it now

Escape leaves without writing anything.

Self-hosted

It looks for a server before it asks for one

Four default ports on the loopback interface are probed at once.

Port	Server
11434	ollama
8080	llama-server
1234	LM Studio
8000	vLLM

If one answers, the address question is skipped and setup goes straight to the model list. The probe takes well under a second whether or not anything is listening.

If nothing answers but ollama is on your PATH, setup offers to start it, since that is a service away rather than a download away.

It measures the machine before recommending a model

When there is no server to find, setup reads the host: memory, cores, CPU vector width, free space where models are stored, and any GPU it can size. The model list is then ranked against that machine rather than printed as a fixed block.

Model	GPU	Download	Best for
qwen3.8:27b	24 GB	18 GiB	Capability
qwen3.5:9b	16 GB	6.6 GiB	Balance
qwen3.5:4b	8 GB	3.4 GiB	Speed and cost

Each row is marked with how it stands against your machine: GPU-resident, memory-resident, or too large to load. The list opens on the row your machine was measured for, and a fourth row covers any server the list does not fit.

The recommendation takes the most capable row that is still quick enough to be worth using and still leaves the machine memory to work with. Fitting and fitting comfortably are different questions, and only the second one is a recommendation.

GPU sizing on NVIDIA hosts

AMD and Intel cards publish their capacity to the kernel and are read from there. The NVIDIA proprietary driver does not, so nvidia-smi is used where it is present. Without it the card is treated as unknown and the recommendation is made against system memory instead, which is conservative rather than wrong.

The guided install

If nothing is listening, ollama is not installed, and the machine can obtain root, setup offers to install it and pull the model you picked.

The offer states what it will do before it does it:

• It downloads and runs https://ollama.com/install.sh, which needs root and will ask sudo for your password.
• It then pulls the model you chose, and names the download size.
• It raises ollama's context length for this machine. See below.

The manual option is the highlighted one. Pressing return through an unread screen never starts a download. Choosing it prints the commands to run by hand instead.

Nothing here is fatal. Every failure falls back to the address prompt and says so on the way, so setup finishing with a manual step beats setup not finishing.

Context length

ollama defaults to a context of 4096 tokens, chosen so a model loads anywhere at all. It is a floor, not a recommendation, and it is smaller than the prompt Oasis CLI sends before you have typed anything. Left alone, the first turn opens over budget and the server truncates every request.

A guided install sizes it instead. Setup takes the largest window whose key-value cache fits in what is left after the model weights and the machine's own reserve, from 128k, 64k, 32k, 16k and 8k. Where the model runs on a GPU, the budget is the card's memory, because that is where the cache is allocated. Where no window fits, none is set, since a window a machine cannot hold stops the model loading.

The value is written as a systemd drop-in at /etc/systemd/system/ollama.service.d/oasis-context.conf, so an ollama upgrade does not carry it away. ollama is restarted and setup waits for it to answer again.

It changes the server, not just this client

The drop-in sets OLLAMA_CONTEXT_LENGTH for the whole service, so it applies to every client of that ollama instance, not only Oasis CLI. Delete the file and restart ollama to undo it. See Limitations.

The chosen value is also written to your config file as context_window, and only if the restart succeeded. See Configuration.

Checks only

For a machine that has no model server yet. It runs the preempt-rt profile against the host straight away: 33 of the 45 checks in the catalogue, covering preemption mode, isolcpus, RT throttling, C-states, measured jitter and control-loop cycle time. The other 12 need a device to point at.

check and audit were never gated on inference, so nothing is withheld by taking this answer. When you do have an endpoint, oasis-agent setup adds it.

The report prints and the question returns, so you can add an endpoint in the same run if one has since become available. Escape finishes.

Non-interactive runs

Setup is interactive and never opens in CI, in a container build, or on a piped install. Those runs need --base-url as before, and the error says so, along with the fact that check and audit do not.

Next

• Configuration for every value setup writes and how to change it.
• Conformance Checks for what the checks-only answer runs.
• Licence for the terms setup ends on.