Installing & Updating

Oasis CLI manages its own installation. Versions are installed side by side, a small launcher decides which one runs, and switching between them, including rolling back, is a one-line change that never touches a running process.

Check System Requirements first.

On-disk layout

~/.oasis/versions/0.4.1/oasis-agent   one immutable directory per version
~/.oasis/versions/0.4.2/oasis-agent
~/.oasis/versions/current             a text file naming the active version
~/.oasis/downloads/                   staging area for in-flight downloads
~/.local/bin/oasis-agent              the launcher: reads `current` and execs it

Path	Override with	Default
Installation root	OASIS_ROOT	~/.oasis
Launcher directory	OASIS_INSTALL_DIR	~/.local/bin

Make sure the launcher directory is on your PATH.

Installing a version

# Install the newest published version and point the launcher at it
oasis-agent install latest

# Install a specific version
oasis-agent install 0.4.2

install is idempotent. Running it on a version that is already on disk performs no download. It simply repoints the launcher. That is also how a rollback is done:

# Roll back to a version already on disk. No download, no network.
oasis-agent install 0.4.1

Updating

# Update to the newest published version
oasis-agent update

From inside the REPL, /update does the same thing and /status reports what is installed and where each setting came from.

An update writes a new directory and rewrites versions/current. It never modifies a file an existing process has open, so:

• A conversation that is running finishes on the version it started on.
• The next conversation you start picks up the new version.
• An in-flight background agent is never interrupted by an update.

Automatic updates

Auto-update is on by default. The agent checks for a newer version at startup and updates itself in the background. An install that does not update is the one that quietly rots, and because each version lands in its own directory an update is cheap and reversible.

The safety property above still holds: a background update never touches a file a running process has open, so a conversation or an in-flight background agent is never interrupted by one.

Turning automatic updates off

Set the durable key:

oasis-agent /config auto_update false

Or in ~/.oasis/config.json:

{ "auto_update": false }

This turns off both the background update and the startup check. oasis-agent update still works when you ask for it explicitly.

For CI and containers, where writing a config file is awkward, set OASIS_DISABLE_AUTOUPDATER to any value. It has the same effect.

/status inside the REPL reports whether auto-update is on and which layer supplied the value.

Pinning a version range

An operator can pin which versions an install may move to with the minimum_version and maximum_version keys in the config file. An update outside those bounds is refused and says which bound blocked it. An invalid bound is ignored rather than enforced, so a bad value cannot freeze a fleet. See Configuration.

Choosing a release store

release_host selects where versions are resolved from. It defaults to the value compiled into the binary at build time, and OASIS_RELEASE_HOST overrides it. Most installs never need to set it; an air-gapped site does. See Air-gapped and offline installs.

EtherCAT capabilities

EtherCAT is raw layer 2. Opening the socket needs CAP_NET_RAW, and reading the interface MTU needs CAP_NET_ADMIN. An ordinary user process holds neither, so install and update grant them for you.

Capabilities attach to a file, and every version is a new file, so this runs on every install, including a repoint to a version already on disk, which may predate the grant.

Granting needs root, and the installer runs as you. It takes the first route the machine allows:

Route	When
Direct setcap	Already running as root: containers, CI, a provisioning system
sudo -n	sudo needs no password, or your credentials are still cached. Silent
sudo with a prompt	A password is needed and there is a terminal to type it on

The last route covers curl … | bash. The pipe takes stdin, but sudo asks on the controlling terminal rather than on stdin, so a piped install still prompts. You type your password once and EtherCAT works.

Unattended installs

Cron, a container build, a CI runner, a host with no sudo, or one with no setcap: there is no terminal to ask on. The install still succeeds, everything except EtherCAT works, and it prints the one command left to run:

installed 0.4.2
EtherCAT needs CAP_NET_RAW and CAP_NET_ADMIN, and they could not be granted here: sudo needs
a password and there is no terminal to ask on.
Everything else works. To enable EtherCAT, run:
  sudo setcap cap_net_raw,cap_net_admin+eip /home/deploy/.oasis/versions/0.4.2/oasis-agent
Re-running the installer also repairs this.

Note the target: the versioned binary, not ~/.local/bin/oasis-agent. That is a #!/bin/sh launcher, and Linux ignores file capabilities on interpreted scripts, so setcap there succeeds and does nothing.

After a manual grant, restart the agent. Capabilities are granted at exec, so a process already running cannot pick them up however the file is set.

oasis-agent doctor reports what the process holds, what the binary carries, and whether an install will grant.

Turning it off

{ "grant_capabilities": false }

OASIS_NO_CAPABILITIES=1 is the environment override. Worth setting on a shared host: capabilities live on the file, so a granted binary hands a raw socket to anyone who can execute it. Modbus and OPC UA are ordinary TCP and need none of this.

Release line

There is one release line. The newest published version wins, and latest is the only pointer.

Target	Accepted	Meaning
latest	Yes	The newest published version
A version string, e.g. 0.4.2	Yes	That exact version
stable	No	There is no promotion tier and no channel to choose

Version retention

Three versions are retained, including the active one. Older versions are pruned automatically on install.

The version the launcher points at is never pruned, even if it is older than the three newest, so an operator deliberately pinned to an old build keeps it.

Checking what you have

# Line 1 is the bare version string. This is the contract scripts parse
oasis-agent version

# Plus the commit and build date this binary was built from
oasis-agent version --verbose

Diagnosing an installation

oasis-agent doctor

doctor reports the versions on disk, which one the launcher runs, where each setting came from, and anything that looks wrong. It is the first thing to run when the version you get is not the version you expect.

First-run configuration

oasis-agent setup

setup asks for the model endpoint and saves it. It runs automatically on your first interactive run when nothing is configured; run it explicitly to change the answer later.

See Configuration for the full resolution order and every available key.

Uninstalling

oasis-agent uninstall

It lists everything it will remove and asks before touching anything.

Removed
~/.local/bin/oasis-agent	Only the managed launcher. See below
~/.oasis/versions/, ~/.oasis/downloads/	Installed versions and staging
~/.oasis/sessions/, ~/.oasis/skills/	Saved conversations and skills
~/.oasis/config.json	Configuration
~/.oasis/audit.jsonl	The audit trail. --keep-audit preserves it
~/.local/state/oasis-agent/	Per-project memory
Your shell profile	Only the fenced PATH block the installer added

Flag	What it does
--dry-run	Print the plan and stop
-y, --yes	Skip the confirmation. Required when stdin is not a terminal
--keep-audit	Keep ~/.oasis/audit.jsonl

What it will not do:

• Delete a launcher you wrote yourself. Anything without the managed marker is reported as left alone.
• Remove the install root recursively. It comes off non-recursively, so a file of your own inside ~/.oasis survives, along with the directory.
• Run without confirmation off a pipe. --yes is required, so an uninstall cannot happen silently inside a provisioning script.

The audit trail is in scope

~/.oasis/audit.jsonl is the actor-stamped record of every write the agent made. On a customer device that may need to outlive the install. Pass --keep-audit, or archive it first. See Audit Trail.

OASIS_ROOT does not isolate everything

The memory store is keyed off HOME, not OASIS_ROOT, so pointing OASIS_ROOT at a scratch directory does not move it. Read the printed list before confirming.

Bringing your own launcher

If you replace ~/.local/bin/oasis-agent with your own script or a symlink, it is left alone. Updates still install into versions/, and your launcher keeps deciding what runs.

The managed launcher carries a marker comment; anything without that marker is treated as operator-owned and never overwritten.

Air-gapped and offline installs

install and update need to reach the release host. On a machine with no route to it, copy the binary into place yourself:

mkdir -p ~/.oasis/versions/0.4.2
cp oasis-agent ~/.oasis/versions/0.4.2/oasis-agent
chmod +x ~/.oasis/versions/0.4.2/oasis-agent
echo 0.4.2 > ~/.oasis/versions/current

Then run oasis-agent doctor to confirm the launcher resolves it. A binary copied straight onto the PATH with no version directory also works. You simply lose update, rollback and retention.