> ## Documentation Index
> Fetch the complete documentation index at: https://docs.make87.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime Management Commands

> Manage the m87 runtime service on edge devices with start, stop, restart, enable, disable, and status commands

## Overview

The m87 runtime is a service that runs on edge devices to enable remote access from the m87 CLI. Runtime management commands allow you to install, configure, and control this service using systemd.

> [!NOTE]
>
> **Runtime commands are only available on Linux systems.** These commands manage the systemd service on edge devices, not on your local workstation.

***

## Prerequisites

* **Linux system** (amd64 or arm64)
* **systemd** installed and running
* **sudo access** (commands automatically use sudo when needed)

***

## Runtime Commands Overview

| Command | Description | Enables on Boot | Starts Service |
| - | - | - | - |
| `start` | Start service now | ✓ | ✓ |
| `stop` | Stop service now | No change | ✗ |
| `restart` | Restart service | No change | ✓ |
| `enable` | Enable auto-start on boot | ✓ | ✗ |
| `enable --now` | Enable and start | ✓ | ✓ |
| `disable` | Disable auto-start | ✗ | No change |
| `disable --now` | Disable and stop | ✗ | ✗ |
| `status` | Show service status | - | - |

***

## Runtime Login

Register the device as a runtime (headless flow, requires approval).

### Syntax

```bash theme={null}
m87 runtime login [OPTIONS]
```

### Options

| Flag | Description |
| - | - |
| `--org-id <ID>` | Register under specific organization ID |
| `--email <EMAIL>` | Register under user's email address |

> [!NOTE]
>
> You must specify either `--org-id` or `--email`, but not both.

### Examples

```bash Register with Organization theme={null}
# Register device under organization
m87 runtime login --org-id my-company
```

```bash Register with Email theme={null}
# Register device under user account
m87 runtime login --email user@example.com
```

### Approval Process

1. Run `m87 runtime login` on the edge device
2. The device shows up as "pending" in your device list
3. From your workstation, approve the device:
   ```bash theme={null}
   m87 devices list
   m87 devices approve <device-name>
   ```
4. The device is now accessible remotely

***

## Runtime Logout

Remove runtime credentials from the device.

```bash theme={null}
m87 runtime logout
```

This deregisters the device and removes local authentication tokens.

***

## Start Runtime Service

Start the runtime service immediately and enable auto-start on boot.

### Syntax

```bash theme={null}
m87 runtime start [OPTIONS]
```

### Options

| Flag | Description |
| - | - |
| `--org-id <ID>` | Organization ID for registration |
| `--email <EMAIL>` | Email address for registration |

### Behavior

1. Installs systemd service file
2. Enables service to start on boot
3. Starts the service immediately
4. Registers device if not already registered

### Examples

```bash Basic Start theme={null}
# Start runtime service
m87 runtime start
```

```bash Start with Registration theme={null}
# Start and register under organization
m87 runtime start --org-id my-company

# Start and register under email
m87 runtime start --email user@example.com
```

> [!TIP]
>
> Use `m87 runtime start` as the quickest way to set up a new device. It handles installation, registration, and startup in one command.

***

## Stop Runtime Service

Stop the running service (keeps enabled at boot).

### Syntax

```bash theme={null}
m87 runtime stop
```

### Behavior

* Stops the currently running service
* Service remains enabled to start on next boot
* Device becomes unreachable until service is started again

### Example

```bash theme={null}
# Stop runtime service
m87 runtime stop
```

> [!NOTE]
>
> Stopping the runtime makes the device inaccessible remotely. You'll need physical or local network access to start it again.

***

## Restart Runtime Service

Restart the service (starts if stopped).

### Syntax

```bash theme={null}
m87 runtime restart [OPTIONS]
```

### Options

| Flag | Description |
| - | - |
| `--org-id <ID>` | Organization ID for registration |
| `--email <EMAIL>` | Email address for registration |

### Behavior

* If running: restarts the service
* If stopped: starts the service
* Matches standard systemd `restart` behavior

### Examples

```bash Basic Restart theme={null}
# Restart runtime service
m87 runtime restart
```

```bash Common Use Case: After Update theme={null}
# Update CLI and restart runtime
m87 update
m87 runtime restart
```

### Remote Update and Restart

Update a remote device's runtime:

```bash theme={null}
# Update and restart remote device
m87 rpi exec -it -- 'm87 update && m87 runtime restart'
```

***

## Enable Runtime Service

Configure service to auto-start on boot.

### Syntax

```bash theme={null}
m87 runtime enable [OPTIONS]
```

### Options

| Flag | Description |
| - | - |
| `--now` | Enable AND start service immediately |
| `--org-id <ID>` | Organization ID for registration |
| `--email <EMAIL>` | Email address for registration |

### Behavior

* **Without `--now`**: Enables service for next boot (doesn't start now)
* **With `--now`**: Enables service AND starts it immediately

### Examples

```bash Enable for Next Boot theme={null}
# Enable auto-start (doesn't start now)
m87 runtime enable

# Device will start runtime on next reboot
```

```bash Enable and Start Now theme={null}
# Enable and start immediately
m87 runtime enable --now

# Equivalent to 'm87 runtime start'
```

***

## Disable Runtime Service

Remove auto-start on boot.

### Syntax

```bash theme={null}
m87 runtime disable [OPTIONS]
```

### Options

| Flag | Description |
| - | - |
| `--now` | Disable AND stop service immediately |

### Behavior

* **Without `--now`**: Disables auto-start (keeps running now)
* **With `--now`**: Disables auto-start AND stops service immediately

### Examples

```bash Disable Auto-Start theme={null}
# Disable auto-start (keeps running now)
m87 runtime disable

# Service runs until stopped or rebooted
```

```bash Disable and Stop theme={null}
# Disable and stop immediately
m87 runtime disable --now

# Service is stopped and won't start on boot
```

***

## Runtime Status

Show local runtime service status.

### Syntax

```bash theme={null}
m87 runtime status
```

### Example Output

```bash theme={null}
m87 runtime status
```

```text theme={null}
● m87-runtime.service - m87 Runtime Service
     Loaded: loaded (/etc/systemd/system/m87-runtime.service; enabled)
     Active: active (running) since Mon 2026-03-01 10:23:45 UTC; 2 days ago
   Main PID: 1234 (m87)
      Tasks: 8 (limit: 4915)
     Memory: 24.5M
        CPU: 1min 32.456s
     CGroup: /system.slice/m87-runtime.service
             └─1234 /usr/local/bin/m87 runtime run
```

***

## Runtime Run (Advanced)

Run the runtime daemon directly (used by systemd service).

### Syntax

```bash theme={null}
m87 runtime run [OPTIONS]
```

### Options

| Flag | Description |
| - | - |
| `--org-id <ID>` | Organization ID for registration |
| `--email <EMAIL>` | Email address for registration |

### Behavior

* Runs in foreground (blocking)
* Registers device if needed
* Waits for approval if pending
* Handles incoming connections

> [!WARNING]
>
> This command is typically only used by the systemd service. For normal operation, use `m87 runtime start` instead.

### Example

```bash theme={null}
# Run runtime in foreground (for testing)
m87 runtime run --email user@example.com
```

***

## Complete Setup Workflow

### On Edge Device

```bash Quick Setup theme={null}
# One command to set up everything
m87 runtime start --email user@example.com

# Device is now:
# - Registered (pending approval)
# - Systemd service installed
# - Service enabled on boot
# - Service running
```

```bash Step-by-Step Setup theme={null}
# 1. Login/register
m87 runtime login --email user@example.com

# 2. Install and start service
m87 runtime start

# 3. Check status
m87 runtime status
```

### On Workstation

```bash theme={null}
# 1. List devices (shows pending)
m87 devices list

# 2. Approve device
m87 devices approve my-edge-device

# 3. Access device
m87 my-edge-device shell
```

***

## Service Management

### The runtime service:

* **Runs as your user** (not root)
* **Managed by systemd** (start/stop/restart)
* **Auto-starts on boot** (when enabled)
* **Handles privilege escalation** with sudo when needed
* **Logs to journald** (view with `journalctl -u m87-runtime`)

### View Service Logs

```bash theme={null}
# View recent logs
journalctl -u m87-runtime -n 50

# Follow logs in real-time
journalctl -u m87-runtime -f

# View logs from today
journalctl -u m87-runtime --since today
```

***

## Troubleshooting

### Service Won't Start

```bash Check Status theme={null}
# View detailed status
m87 runtime status

# View logs
journalctl -u m87-runtime -n 100
```

```bash Common Fixes theme={null}
# Restart service
m87 runtime restart

# Re-login if credentials expired
m87 runtime logout
m87 runtime login --email user@example.com

# Check systemd service
systemctl status m87-runtime
```

### Device Unreachable

```bash theme={null}
# On the edge device, check if runtime is running
m87 runtime status

# If stopped, start it
m87 runtime start

# Check network connectivity
ping make87.com

# View runtime logs for errors
journalctl -u m87-runtime -f
```

### Permission Errors

```bash theme={null}
# Ensure user is in correct groups
groups

# Re-login to apply group changes
# (or reboot)
```

***

## Command Behavior Summary

### Start vs Enable

* **`start`**: Enable on boot + start now
* **`enable`**: Only enable on boot (doesn't start now)
* **`enable --now`**: Same as `start`

### Stop vs Disable

* **`stop`**: Stop now (keeps enabled on boot)
* **`disable`**: Only disable on boot (keeps running now)
* **`disable --now`**: Disable on boot + stop now

### Restart

* Restarts if running
* Starts if stopped
* Standard systemd behavior

***

## Best Practices

> [!TIP]
>
> **Runtime management tips:**
>
> 1. **Always enable on boot** - Use `start` or `enable --now` for production
> 2. **Monitor logs** - Check `journalctl` after startup for issues
> 3. **Update regularly** - Keep runtime updated with `m87 update && m87 runtime restart`
> 4. **Use organizations** - Register devices under org IDs for better fleet management
> 5. **Document devices** - Keep track of device names and registration details

***

## Related Commands

* [Device Access](https://docs.make87.com/commands/device-access.md) - Access devices after runtime is running
* [Deployments](https://docs.make87.com/commands/deployments.md) - Deploy applications to runtime devices


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.