portless-deployer

name	portless-deployer
description	Portless deployment for local services — expose local servers via tunnels, manage subdomains, configure routing, and deploy preview environments.
version	0.1.0
author	Jero (LATTICE / MARPA Design Studios)
triggers	["deploy with portless","expose this locally","create a tunnel","portless subdomain","share this server"]
tools	["Bash","Read","Write"]

Portless Deployer

USE WHEN the user wants to expose local services via Portless tunnels, create subdomains for development servers, share local apps with external collaborators, or set up preview environments for Grafts.

What It Does

Manages Portless tunnel deployments — exposing local development servers (marimo dashboards, FastAPI backends, Grafthouse sandboxes) to the internet via stable subdomains without port forwarding or firewall configuration.

Core Commands

# Expose a local port
portless expose 8080

# Expose with a custom subdomain
portless expose 8080 --subdomain my-graft

# List active tunnels
portless list

# Stop a tunnel
portless stop my-graft

# Check status
portless status

Common Workflows

Expose a marimo Dashboard

# Start marimo
marimo run dashboard.py --port 2718

# Expose via portless
portless expose 2718 --subdomain graft-dashboard

Expose a FastAPI Backend

# Start the API
uv run uvicorn main:app --port 8000

# Expose via portless
portless expose 8000 --subdomain graft-api

Expose a Grafthouse Sandbox

# During a Graftline build, expose the sandbox for live preview
portless expose 3000 --subdomain grafthouse-preview

Integration with GRAFTKIT

Autograft Preview

During the Graftline, expose the built Graft for review before Autograft:

1. Builder generates the Graft
2. Validator runs smoke tests
3. Portless exposes the running Graft on a preview subdomain
4. User reviews live output
5. On approval, Autograft proceeds

Control Surface Sharing

Expose marimo control surfaces for remote observation during builds:

portless expose 2718 --subdomain control-surface-{graft-name}

MCP Service Management

Portless also manages stdio-based MCP services defined in .mcp.json:

{
  "mcpServers": {
    "my-service": {
      "command": "uv",
      "args": ["run", "my_service.py"],
      "env": { "SERVICE_CONFIG": "/path/to/config.json" }
    }
  }
}

Common MCP Services

Service	Command	Purpose
GitHub MCP	npx @modelcontextprotocol/server-github	Repo access, PR management
Repomix	npx repomix --mcp	Codebase packing
AgentMail	npx agentmail-mcp	Agent-to-agent messaging
Custom DB	uv run db_service.py	Database query interface

Health Monitoring

The hourly-service-health scheduled task (MARPA-39) monitors all Portless services. See docs/SCHEDULED_TASKS.md.

Rules

• Always use --subdomain for stable, memorable URLs
• Stop tunnels after builds complete to free resources
• Do not expose services with sensitive data without explicit user approval
• Use portless for development/preview only — production deployments go through Vercel or cloud
• Check portless list before creating new tunnels to avoid duplicates