Your first program

There are two ways to build and run code on mutexer. They are separate flows, and this page covers both. Pick the one that matches how you want to work. You can come back and do the other later.

	Magnum Coder	Oasis CLI
Where you work	The browser, in the Mutexer Cloud Portal	A terminal, on the machine doing the work
What you end up with	A Python program built in the cloud and deployed to a connected device	A harness running on your machine, writing and checking code alongside you
Needs a connected device	Yes	No
Needs a model endpoint	No	Yes, your own
What you install	The agent, on the target device	One binary, on the machine you work on

Not sure which?

If your goal is "get a program running on a device", start with Magnum Coder. If your goal is "help me write and verify industrial code on this machine", start with Oasis CLI.

---

Flow 1: Magnum Coder, in the browser

This flow takes you from an empty project to a Python program running on a device.

It assumes you have already created an account, environment and project.

Magnum Coder needs the agent on a device

Magnum Coder edits and builds in the cloud, but the agent is what receives a deployment and runs the program. Connecting a device installs the agent, and it is the first step below. Until a device is connected there is nothing to deploy to.

Connecting a device

To connect your first device click "Add" in the Device tree-view facet and name your device.

There are two options

Physical device supports hard or soft real-time. Useful when you want to control real inputs and outputs especially with hard realtime timing constraints.

Virtual machine supports soft real-time only. Create a cloud based instance. Useful for workloads where you need more power but don't need hard realtime. Also, very useful for simulation when you don't have a physical device handy.

TIP

Hard real-time means that the programs launched by the agent will have strict timing controls. This makes it suitable for things like machine control, robotics and process control where determinism is a key requirement.

You also choose an install type at this point, which decides the capabilities the agent is built with. Core has no remote access; Advanced adds CloudLink and the remote terminal. For more information, see Capabilities.

If you have selected a physical device, copy the connection command to the terminal of your device and run it as root user.

Further information on the agent such as compatibility, installation and upgrading can be found here Agents

INFO

The installation is fully automated and typically takes 5-10 minutes. However, it can vary depending on the performance of the hardware.

Once the agent is fully installed it will indicate that in both the terminal of the device and in the "Device" treeview facet with a "Connected" flag.

Code

Once your device is fully connected a default sample python program will already be created.

Physical devices > [Device name] > MyProgram > Files > python.py

The default code snippet is below. This very simple program will print "Hello world" out to the terminal.

class PythonProgram:
	def on_initialize(self):
  		# This method is invoked once, the first time the program runs.
  		pass

	def on_cycle(self):
        # This method is invoked every cycle. Put your per-cycle logic here.
		print(f"Hello world!")

WARNING

The entire program must be contained within the PythonProgram class. This is due to the architecture of the agent. It will not compile if it does not conform to this structure.

def on_initialize(self):

Code that should only run once on program initialisation should be inserted into the on_initialize(self) definition.

def on_initialize(self):
    # This method is invoked once, the first time the program runs.
    pass

def on_cycle(self):

Code that should only run every cycle continuously should be inserted into the on_cycle(self) definition. The mutexer platform is centred around programs that continuously execute in a loop as that is the typical mode that industrial automation programs run in. Usually the loop will run as fast as possible but no slower than the maximum watchdog time.

def on_cycle(self):
    # This method is invoked every cycle. Put your per-cycle logic here.
    print(f"Hello world!")

TIP

The on_cycle(self) section execution at runtime is timed and monitored by the agent. If the time it takes to execute this section of code when set to hard real-time mode exceeds the watchdog timer the program will halt with and error.

Start-up file

The entry point file for the entire program is set in the program settings.

Physical devices > [Device name] > MyProgram > Settings

WARNING

That means all file if they are to run must be called directly by the start-up file or by a file that can trace its call origin to the start-up file.

Build

Now that your have created your first program it's time to built it.

To build your program click the "Build only" button at the top toolbar in the text editor or right-click on your program in the "Device" treeview.

The progress and output of the build process can be viewed in the "Deployments" facet.

INFO

The build can be cancelled anytime by click the corresponding "Cancel" button in the "Deployments" facet.

If the build did not succeed further information about the error will be output to the "Build Output" section.

Deployment

Another option to build your program is the "Build and Deploy" button in the top toolbar in the text editor or in the dropdown when right-clicking on the program itself.

DANGER

However, in this instance after the build process is finished the program will immediately begin to be deployed to the device. As soon as the deployment process is complete the program will start running.

Therefore, please take care when deploying programs to ensure that it is safe to do so.

Programs can be started and stopped from the Applications tab of Agent Settings.

Devices > [Device name] > Agent > Applications

For more information, see Agent Settings.

Congratulations, you have now successfully deployed your first program from the cloud to your device.

---

Flow 2: Oasis CLI, in the terminal

This flow takes you from nothing installed to a working session on the machine in front of you. Nothing here needs a device connected to the platform.

Install it

curl -fsSL https://get.mutexer.com/oasis/install.sh | bash

One static binary, no runtime. It installs to ~/.local/bin, so make sure that directory is on your PATH. Works on Linux, and on Windows inside a WSL 2 distribution.

For architectures, kernel requirements and the on-disk layout, see System Requirements and Installing & Updating.

Point it at a model

Oasis CLI has no built-in endpoint and never dials one. You supply it, so nothing leaves your network unless you point it out.

oasis-agent setup

setup asks for the model endpoint and saves it. It also runs automatically the first time you start an interactive session with nothing configured.

An endpoint is required

There is no default. Configure it once with setup, export OASIS_BASE_URL, or pass --base-url on every run. See Configuration.

Start a session

cd /path/to/your/project
oasis-agent

That opens an interactive session in the current directory. Type a request in plain language:

read the files in this project and tell me what it does

The agent asks permission before anything that writes or runs. Shift+Tab cycles the permission mode, and /help lists everything you can type. See Interactive REPL.

Run one prompt and exit

For scripts, cron and CI, where there is no terminal:

oasis-agent -p "list every TODO comment in this project"

See One-shot & Scripting.

Reach the plant

This is what separates Oasis CLI from a general coding tool. Turn on a capability pack and protocol operations become things the agent can do in the same turn it writes code.

{
  "modules": {
    "modbus": true,
    "opcua": true
  }
}

Put that in ./.oasis/config.json in your project. Modbus, OPC UA and EtherCAT are available. See Capability Packs.

Protocol writes touch real equipment

Tools that write registers, write SDOs or energise outputs are hard stop: they prompt every time, in every permission mode, and --skip-permissions does not waive them. See Permission Model.

Check a machine

No model endpoint is needed for this one. It measures the machine and hands you the result:

oasis-agent check --module preempt-rt

See Conformance Checks.

Where to go next

If you want to	Read
Understand what the agent installs on a device	Agents
Choose an agent install type	Capabilities
Know what hard real-time actually costs	Real vs Soft Real-time
Go deeper on the CLI	Oasis CLI