vllm-ctl

A CLI tool to manage vLLM Metal on Apple Silicon Macs. Start, stop, and expose a local LLM server with one command — including an ngrok tunnel for use with Cursor IDE and other OpenAI-compatible clients that block localhost.

Why

Running local LLMs on Apple Silicon via vLLM Metal works, but managing the server, checking status, and exposing it to tools like Cursor involves juggling multiple processes. vllm-ctl wraps all of that into a single CLI:

• One command to start — launches vLLM Metal + ngrok tunnel
• One command to stop — kills both cleanly
• Prints Cursor-ready config — copy-paste into Cursor settings
• Status, logs, test — all built in

Requirements

• macOS on Apple Silicon (M1/M2/M3/M4)
• Homebrew
• ngrok account (free tier works) — for tunnel support
• Hugging Face account — for model downloads

Install

curl -fsSL https://raw.githubusercontent.com/yafatek/vllm-ctl/main/install.sh | bash

Or manually:

git clone https://github.com/yafatek/vllm-ctl.git
cd vllm-ctl
chmod +x vllm-ctl
ln -sf "$(pwd)/vllm-ctl" "$HOME/.local/bin/vllm-ctl"

Then install the vLLM Metal backend:

vllm-ctl install

Setup

Hugging Face login (required for gated models)

vllm-ctl login

ngrok auth (required for tunnel)

ngrok config add-authtoken <your-token>

Get your free token at dashboard.ngrok.com.

Usage

Start the server

vllm-ctl start

Output:

Starting vLLM Metal server...
Model: mlx-community/Qwen3-Coder-30B-A3B-Instruct-4bit
Port:  8000

Waiting for server..............
Server ready!
Starting ngrok tunnel...
Waiting for tunnel URL....

=== vLLM Metal ===

  Model:     mlx-community/Qwen3-Coder-30B-A3B-Instruct-4bit
  Local:     http://localhost:8000/v1/
  Tunnel:    https://your-subdomain.ngrok-free.dev/v1/

  Cursor Settings:
    API Key:   sk-local
    Base URL:  https://your-subdomain.ngrok-free.dev/v1
    Model:     mlx-community/Qwen3-Coder-30B-A3B-Instruct-4bit

Start with a different model

vllm-ctl start mlx-community/Qwen2.5-Coder-14B-Instruct-4bit

Stop everything

vllm-ctl stop

Check status

vllm-ctl status

Get the tunnel URL (for Cursor)

vllm-ctl url

Send a test prompt

vllm-ctl test "Write a Python function that checks if a number is prime"

Pre-download a model

vllm-ctl download mlx-community/Qwen3-Coder-30B-A3B-Instruct-4bit

All Commands

Command	Description
vllm-ctl install	Install vLLM Metal backend
vllm-ctl uninstall	Remove vLLM Metal and optionally cached models
vllm-ctl start [model]	Start server + ngrok tunnel
vllm-ctl stop	Stop server + tunnel
vllm-ctl restart [model]	Restart both
vllm-ctl status	Server state, tunnel URL, memory, cached models
vllm-ctl url	Print tunnel URL
vllm-ctl logs	Tail server logs
vllm-ctl logs-tunnel	Tail ngrok logs
vllm-ctl models	List loaded models
vllm-ctl test [prompt]	Send a test prompt
vllm-ctl download <model>	Pre-download a model
vllm-ctl login	Authenticate with Hugging Face
vllm-ctl clean-cache	Remove partially downloaded files

Using with Cursor IDE

1. vllm-ctl start
2. Copy the tunnel URL from the output
3. In Cursor: Settings → Models → OpenAI API Key
   • API Key: sk-local (any non-empty string)
   • Override OpenAI Base URL: <tunnel-url>/v1
4. Click Add Model and enter the model name from vllm-ctl status
5. Select the model in chat or Cmd+K

Note: The ngrok URL changes on each restart. Run vllm-ctl url to get the current one.

Recommended Models for 32GB Apple Silicon

Model	VRAM	Speed	Quality
mlx-community/Qwen3-Coder-30B-A3B-Instruct-4bit	~17GB	Good	Excellent
mlx-community/Qwen2.5-Coder-14B-Instruct-4bit	~8GB	Fast	Very Good
mlx-community/Qwen2.5-Coder-7B-Instruct-4bit	~4GB	Very Fast	Good

Environment Variables

Variable	Default	Description
VLLM_PORT	8000	Server port
VLLM_NO_TUNNEL	0	Set to 1 to skip ngrok tunnel

How It Works

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Cursor IDE  │────▶│  ngrok       │────▶│  vLLM Metal  │
│  (or any     │     │  tunnel      │     │  server      │
│  OpenAI      │     │              │     │  (MLX on     │
│  client)     │     │  public URL  │     │  Metal GPU)  │
└──────────────┘     └──────────────┘     └──────────────┘

License

Apache 2.0