---
layout: default
title: opencode-studio
parent: WireGuard VPN
---

# opencode-studio

MLX workflow wrapper for server and client machines.

## Overview

This script manages the MLX LM server connection between a server (where MLX runs) and clients (which connect via SSH tunnel). It auto-detects the machine role based on hostname or can be forced with flags.

**Flexible Connection**: Works over VPN, local network, or internet — just specify the server hostname.

## Usage

```bash
opencode-studio <command> [OPTIONS]
```

## Commands

| Command | Description |
|---------|-------------|
| `status` | Check if MLX server is running and show models |
| `up`, `start` | Start MLX server (local) or open SSH tunnel (remote) |
| `down`, `stop` | Stop MLX server (local) or close SSH tunnel (remote) |

## Options

| Option | Description | Default |
|--------|-------------|---------|
| `-p, --port <n>` | MLX port | 11434 |
| `-s, --server <host>` | Server hostname for SSH | studio |
| `--local` | Force local mode (start MLX server) | auto-detect |
| `--remote` | Force remote mode (SSH tunnel) | auto-detect |
| `-n, --dry-run` | Print actions without executing | - |
| `-v, --verbose` | Verbose output | - |
| `-h, --help` | Show help | - |

## Role Detection

The script auto-detects whether it's running on a server or client via hostname:

- **Server role**: Hostnames matching `studio`, `mac-studio`, or `server`
- **Client role**: Hostnames matching `air`, `macbook-air`, or `laptop`

Customize the `_is_server()` and `_is_client()` functions in the script for your hostnames.

## Examples

### Server (runs MLX)

```bash
opencode-studio status
opencode-studio up
```

### Client (connects to server)

```bash
# Auto-detect role, connect to default server
opencode-studio status
opencode-studio up

# Connect to specific server
opencode-studio up --server myhost

# Force client mode
opencode-studio up --server 192.168.1.10 --remote
```

### Cross-Platform Use

Connect to any Linux/macOS server running MLX:

```bash
# Over local network
opencode-studio up --server 192.168.1.10

# Over VPN
opencode-studio up --server 10.0.0.5

# Over internet (with proper SSH setup)
opencode-studio up --server mlx.example.com
```

## MLX API

Once connected, the MLX API is available at `http://localhost:11434`:

```bash
curl http://localhost:11434/v1/models
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "mlx-model", "messages": [{"role": "user", "content": "Hello"}]}'
```

## Decoupled from VPN

This script works independently of the WireGuard VPN. You can:
- Use it with VPN (recommended for security)
- Use it over local network
- Use it over the internet (with SSH key authentication)

The `--server` flag accepts any hostname or IP address.

## See Also

- [WireGuard VPN index](index.md)