> ## 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.

# Quick start

> Get up and running with m87 in 5 minutes

Get connected to your first edge device in just a few minutes. This guide walks you through installing m87, setting up a device, and running your first commands.

<Info>
  **Prerequisites:** m87 installed on your developer machine ([installation guide](/installation))
</Info>

## Overview

You'll complete four steps:

1. Authenticate on your developer machine
2. Start the runtime on an edge device
3. Approve the device registration
4. Start using the device

<Steps>
  <Step title="Authenticate on your developer machine">
    Login to create your account. This opens your browser for OAuth authentication:

    ```bash theme={null}
    m87 login
    ```

    After successful authentication, your credentials are stored locally in `~/.config/m87/`.
  </Step>

  <Step title="Start the runtime on your edge device">
    On the edge device (e.g., Raspberry Pi, NVIDIA Jetson, server), install m87 and start the runtime:

    ```bash theme={null}
    # Install m87 on the device
    curl -fsSL https://get.make87.com | sh

    # Start the runtime
    m87 runtime run --email you@example.com
    ```

    This registers the device and prints a request ID:

    ```
    Device registration pending approval.
    Request ID: req_abc123xyz
    Waiting for approval...
    ```

    The runtime waits for approval before connecting.
  </Step>

  <Step title="Approve the device">
    Back on your developer machine, approve the pending device:

    ```bash theme={null}
    m87 devices approve req_abc123xyz
    ```

    Or approve via the web UI at [make87.com/devices](https://make87.com/devices).

    Once approved, the runtime on the edge device automatically connects and starts accepting commands.
  </Step>

  <Step title="Start using your device">
    List your devices:

    ```bash theme={null}
    m87 devices list
    ```

    You'll see output like:

    ```
    NAME              STATUS    LAST SEEN
    my-jetson-01      online    1m ago
    ```

    Now you can interact with your device!
  </Step>
</Steps>

## Try these commands

Once your device is connected, try these common operations:

### Open a shell

Get an interactive shell on the remote device:

```bash theme={null}
m87 my-jetson-01 shell
```

Type `exit` or press `Ctrl+D` to close the shell.

### Execute a command

Run a single command:

```bash theme={null}
m87 my-jetson-01 exec -- uname -a
```

### Forward a port

Forward port 8080 from the remote device to your local machine:

```bash theme={null}
m87 my-jetson-01 forward 8080
```

Now access `http://localhost:8080` to reach the service running on the device.

### Check Docker containers

List running containers:

```bash theme={null}
m87 my-jetson-01 docker ps
```

### Copy files

Copy a file from your local machine to the device:

```bash theme={null}
m87 cp ./myapp my-jetson-01:/home/user/myapp
```

Or copy from the device to your local machine:

```bash theme={null}
m87 cp my-jetson-01:/var/log/app.log ./app.log
```

### Sync directories

Sync a local directory to the device (rsync-style):

```bash theme={null}
m87 sync ./src my-jetson-01:/app/src
```

Add `--watch` to continuously sync on file changes:

```bash theme={null}
m87 sync --watch ./src my-jetson-01:/app/src
```

## Set up runtime as a service

To keep the runtime running persistently on your edge device, set it up as a systemd service:

```bash theme={null}
# On the edge device
m87 runtime start
```

This enables the runtime to start automatically on boot.

<Info>
  The runtime service runs as your user (not root) and automatically restarts on failure.

  Use `m87 runtime status` to check the service status or `m87 runtime stop` to stop it.
</Info>

## What's next?

<CardGroup cols={2}>
  <Card title="Port forwarding" icon="arrow-right-arrow-left" href="/commands/port-forwarding">
    Forward ports, sockets, and serial devices
  </Card>

  <Card title="File transfer" icon="files" href="/commands/file-transfer">
    Copy and sync files with remote devices
  </Card>

  <Card title="Deployments" icon="rocket" href="/commands/deployments">
    Deploy containerized applications
  </Card>

  <Card title="SSH setup" icon="terminal" href="/guides/ssh-setup">
    Use standard SSH tools with m87
  </Card>
</CardGroup>

## Troubleshooting

### Device not appearing after approval

Wait a few seconds for the connection to establish. Check the runtime logs on the device:

```bash theme={null}
# On the device
m87 runtime status
```

### Authentication issues

Re-authenticate if your session expires:

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

### Can't connect to device

Ensure the runtime is running on the device:

```bash theme={null}
# On the device
m87 runtime status
```

If stopped, start it:

```bash theme={null}
# On the device
m87 runtime start
```

<Card title="Need help?" icon="question" href="https://github.com/make87/m87/issues">
  Report issues or ask questions on GitHub
</Card>