Port

Port is a CLI-first system for building, launching, and operating isolated Linux workloads in microVMs across local and hosted environments.

It keeps one operator vocabulary across lanes:

• port doctor for host and lane checks
• port artifacts for build, validate, push, and pull
• port machine for lifecycle and status
• port guest for exec, copy, PTY, logs, and forward
• port service for secrets, services, and sandboxes

Current Shape

• Default local lane: Firecracker with standard protection on Linux
• Hosted lane: control plane plus node agent with the same machine, guest, and service verbs
• SSH-managed remote lane: one bounded Linux lifecycle slice for machine launch, status, and stop through mode = "ssh" with explicit route and ownership output
• Attached volume first slice: one persistent host-file attached volume on the local Firecracker standard lane with explicit host path and ownership output
• Hosted stateless K3s first slice: one hosted control plane, one host group, one server machine, one or more worker machines, and cluster access through the canonical machine and guest verbs instead of a second Kubernetes-only command family
• Additional proof-backed lanes: Cloud Hypervisor standard, AVF standard, and prepared-node Firecracker/PVM on x86_64

Quick Start

port doctor
port --config examples/port.toml artifacts build --artifact demo-kernel --architecture native
port --config examples/port.toml machine launch --machine demo
port --config examples/port.toml machine list
port --config examples/port.toml guest exec --machine demo -- /bin/sh -lc 'cat /proc/version'

Use examples/port.toml for the checked-in repo workflow. Detailed config edits and longer examples now live in CONFIGURATION.md. The first hosted stateless K3s workflow, boundaries, and proof command live in docs/operators.md. The first direct-runtime attached-volume workflow and proof command live in docs/operators.md. The first hosted app proof path, repo-level review surface, and current boundaries also live in docs/operators.md. The first installable release contract and support matrix live in docs/install.md. Packaged macOS AVF workflows still use the canonical port CLI plus an external PORT_AVF_LAUNCHER helper; distributed macOS targets remain bounded by Apple's virtualization entitlement requirements described in docs/avf.md.

Mission Report

just mission

That shows a compact mission report with board-backed goal status, recent achievements, and a human-facing artifact gallery for the active mission.

For the current hosted app proof slice, just mission is the repo-level review surface:

• it points at scripts/hosted-http-app-demo.sh as the runnable hosted app workflow
• it points at scripts/render-hosted-http-app-proof.sh plus the recorded GIF and cast artifact for review
• it stays named mission until upstream keel screen exists and Port can hard-cut to just screen
• it uses the current renderer-backed cast/GIF path today; future atxt adoption remains explicit follow-on work

Documentation Map

Root Contracts

Document	Purpose
CONSTITUTION.md	Non-negotiable product and workflow rules
ARCHITECTURE.md	System boundaries, ownership, and major components
CONFIGURATION.md	Config model, environment variables, and detailed workflow examples
RELEASE.md	Current release contract and validation checklist
EVALUATIONS.md	Verification and evidence expectations
AGENTS.md	Shared AI-agent workflow contract

Focused Guides

Document	Purpose
docs/operators.md	Operator-oriented overview and platform guidance
docs/install.md	Installable release contract, support matrix, and package boundaries
docs/hosted.md	Hosted control-plane, node-agent, and service workflows
docs/cloud.md	Cloud-provider and hosted-lane boundaries
docs/artifacts.md	Artifact references, variants, and backends
docs/pvm.md	Firecracker/PVM host-kit and artifact-kit contract
docs/avf.md	Apple Virtualization Framework lane
docs/sdk.md	Hosted SDK and typed client surface

Platform Summary

Environment	What Port supports today
Linux	Full local Firecracker workflow plus hosted control-plane demos
macOS	AVF local workflow through the canonical machine and guest verbs
Windows	Linux-backed workflow through WSL or a remote Linux host; no native install package in the first slice

Use docs/install.md for the installable release contract, docs/operators.md for the platform guide, and CONFIGURATION.md for the detailed configuration and workflow examples.