visionservex 1.1.0

A permissive-license-aware framework for serving modern computer vision models locally and over Cloudflare Tunnel.

VisionServeX

Local-first computer vision API gateway — secure, private, and honest.
Serve modern CV models on your machine. Local-only by default. No data retained.

---

What is VisionServeX?

VisionServeX is an open-source, permissive-license-aware Python framework for running modern computer vision models locally and exposing them through a stable HTTP API. It works as a local model gateway: start it once, call any supported model through one clean API.

Privacy-first design:

• Binds to 127.0.0.1 by default — nothing leaves your machine.
• Images are decoded in memory for inference and never written to disk by default.
• No data is retained between requests by default.
• Log redaction removes tokens, base64, and API keys from all output.

⚠️ No end-to-end encryption claimed. VisionServeX cannot provide E2E encryption in the cryptographic sense — the inference server must see plaintext image tensors to run models. We provide local-first processing, no-retention defaults, optional encryption-at-rest for job metadata, and auth for public mode. See docs/privacy.md.

---

Quickstart (CPU, 5 minutes)

pip install 'visionservex[server,hf,rfdetr]'

visionservex getting-started      # personalized guide
visionservex pull rfdetr-nano     # fast COCO detection, CPU-capable
visionservex serve                 # http://127.0.0.1:8080

curl -F "image=@image.jpg" -F "model_id=rfdetr-nano" \
     http://127.0.0.1:8080/detect | jq

---

Python Client

from visionservex import Client, VisionModel

# Direct inference (local, no server needed)
result = VisionModel("dfine-s").predict("image.jpg")

# Via local gateway
client = Client("http://127.0.0.1:8080")
result = client.detect("rfdetr-nano", "image.jpg")
result = client.grounded_segment("grounded-sam2", "image.jpg", prompt="car, person")
result = client.classify("swinv2-tiny", "image.jpg")

---

What works today

Family	Models	Task	Status	Install
Mock	mock-*	All	stable	base
RF-DETR	rfdetr-nano/small/…	detect	beta	[rfdetr]
RF-DETR-Seg	rfdetr-seg-nano/small/…	segment	beta	[rfdetr]
D-FINE	dfine-n/s/m/l/x	detect	beta	[hf]
Grounding DINO	grounding-dino-tiny/…	open-vocab detect	beta	[hf]
SwinV2	swinv2-tiny/small/base/large	classify	beta	[hf]
SAM v1	sam-vit-base/large/huge	foundation segment	beta	[hf]
SAM 2	sam2-hiera-tiny/small/…	foundation segment	beta	[hf]
Grounded SAM	grounded-sam	grounded segment	beta	[hf]
Grounded-SAM2	grounded-sam2	grounded segment	beta	[hf]
OneFormer	oneformer-swin-large/…	semantic/panoptic	beta	[hf]
RTMPose	rtmpose-s/m/…	pose	docker_checkpoint_required	openmmlab
RTMDet-R/R2	rtmdet-r*/r2*	OBB	docker_checkpoint_required	openmmlab
ONNX export	SwinV2	—	working	[onnx]
TensorRT	—	—	experimental/dry-run	—

GPU: CUDA verified on RTX 5080 for 6+ model families. Run visionservex gpu smoke-test on your hardware.
MPS (Apple Silicon): Implemented, not maintainer-verified (no test hardware). See docs/gpu_validation.md.
VRAM safety: Desktop GPU guard reserves 3 GB for GUI/system. GPU tests run serially by default. See docs/gpu_safety.md.

"beta" means: CPU-verified, CUDA-verified when applicable, CLI/Python/gateway tested. No known regressions. May have edge cases.

---

Known limitations

• OpenMMLab (RTMPose, RTMDet-R/R2, Co-DINO, InternImage): Requires the OpenMMLab toolchain and manually-obtained checkpoints. Returns CHECKPOINT_REQUIRED structured error — no fake output. See docs/openmmlab_expert_models.md.
• TensorRT: ONNX export works for SwinV2. TensorRT engine build requires trtexec and is not implemented inside VisionServeX. See docs/tensorrt.md.
• Apple MPS: Implemented but not maintainer-verified. Users are encouraged to run visionservex mps smoke-test --models swinv2-tiny,sam2-hiera-tiny on Apple Silicon and report results.
• In-flight cancellation: Queued jobs can be cancelled. In-flight inference may complete before cancellation takes effect.

---

Security and Privacy

# Check your current security posture
visionservex security audit --json

# Switch to public-mode configuration
visionservex security mode cloudflare_private --apply

# Generate an API key for development
visionservex gateway token

# Verify log redaction works
visionservex security test-redaction

# See what temp files exist
visionservex privacy inspect-cache
visionservex privacy cleanup --dry-run

Security modes:

Mode	Binding	Auth	Notes
local_private	127.0.0.1	Optional	Default, safest
lan_private	LAN	Required	TLS recommended
cloudflare_private	127.0.0.1 + tunnel	Required	Cloudflare Access recommended
production_multi_user	127.0.0.1 + proxy	Required	Encrypted job store, audit logs

---

Safe Cloudflare Tunnel

export VISIONSERVEX_AUTH__ENABLED=true
export VISIONSERVEX_AUTH__API_KEY=$(visionservex gateway token 2>&1 | grep "API key:" | awk '{print $NF}')

visionservex tunnel config --domain api.yourdomain.com --out tunnel.yaml
visionservex serve &
visionservex tunnel run tunnel.yaml --i-understand-this-is-public

---

GPU Safety

# Check VRAM state and safety budget
visionservex gpu guard-status

# List GPU compute processes (GUI processes are protected)
visionservex gpu processes

# Safely clean up VisionServeX/pytest GPU processes
visionservex gpu cleanup --dry-run
visionservex gpu cleanup --yes

See docs/gpu_safety.md and docs/parallel_safety.md.

---

Temporary Colab GPU worker (optional)

Run VisionServeX on a Google Colab GPU as a short-lived remote worker. Good for demos and benchmarks, not for production — Colab sessions can disconnect at any time.

# Inside a Colab notebook:
!pip install -U 'visionservex[server,hf,rfdetr]'
!visionservex colab doctor
!visionservex gateway start --profile colab-gpu-worker

A copy-paste notebook lives at examples/colab/VisionServeX_Colab_GPU_Worker.ipynb. Full guide: docs/colab_gpu_worker.md.

Tunnel exposure requires auth (visionservex colab token) and the explicit --i-understand-this-is-public flag. The CLI refuses otherwise.

---

Installation

pip install visionservex                   # base (no heavy deps)
pip install 'visionservex[server]'         # + HTTP API server
pip install 'visionservex[hf]'             # + HF Transformers (D-FINE, GD, SwinV2, SAM, SAM2, OneFormer)
pip install 'visionservex[rfdetr]'         # + RF-DETR and RF-DETR-Seg
pip install 'visionservex[server,hf,rfdetr]'  # full recommended

OpenMMLab (RTMPose, RTMDet-R): Docker sidecar or pip install openmim && mim install mmengine mmcv mmpose. See docs/openmmlab_expert_models.md.

---

Syntax Contract

All 222 documented CLI/Python/API examples are covered and verified. No example is allowed to silently fail or return a raw traceback.

visionservex syntax audit             # verify 222 examples, failing must be 0
visionservex validation run release   # run full CI test suite

---

Documentation

Beginner quickstart	5-minute guide
Local gateway	Gateway commands and Python client
Security	Threat model, modes, configuration
Privacy	No E2E claim, retention policy, encryption
Threat model	What we protect and what we don't
Model zoo	All 68 models with current status
Model downloads	Download system, auto-pull
GPU safety	VRAM guard, cleanup, emergency recovery
Parallel safety	Model concurrency policies, benchmarks
Colab GPU worker	Run VisionServeX on a Colab GPU for demos
OpenMMLab expert	RTMPose, RTMDet-R, Co-DINO, InternImage
Cloudflare Tunnel	Public mode safely
GPU validation	CPU/CUDA/MPS status
TensorRT	ONNX export and TensorRT roadmap
Benchmarks	Latency numbers
Syntax contract	222 verified examples
Troubleshooting	Common errors
About	Author, citation

---

License and model licenses

Apache-2.0. See LICENSE and NOTICE.

Each integrated model retains its own upstream license. Review model, checkpoint, and dataset licenses before commercial use. See docs/model_licenses.md.

---

Citation

@software{sajjadi2026visionservex,
  author = {Arash Sajjadi},
  title  = {{VisionServeX: A permissive-license-aware framework for local CV model serving}},
  year   = {2026},
  url    = {https://github.com/arashsajjadi/VisionServeX},
  note   = {Developed under the supervision of Prof. Mark Eramian, University of Saskatchewan.}
}

Author: Arash Sajjadi — PhD Candidate, Department of Computer Science, University of Saskatchewan
Supervision: Prof. Mark Eramian, Computer Vision Lab
(This project is not an official product of the University of Saskatchewan.)