docs/shape.json
Ref: Size: 20.3 KiB History
{
"module": "github.com/a73x/eitri",
"packages": [
{
"importPath": "cmd/eitri",
"plane": "binaries",
"synopsis": "Command eitri is the end-user client: SSH into fleet VMs through the jump gate with self-signed short-lived certs (eitri ssh) and register tenant user CAs (eitri ca upload).",
"imports": [
"internal/cli",
"internal/version"
]
},
{
"importPath": "cmd/eitri-agent",
"plane": "binaries",
"synopsis": "eitri-agent: BYO-hardware agent.",
"imports": [
"internal/agent/run",
"internal/version"
]
},
{
"importPath": "cmd/eitri-apispec",
"plane": "binaries",
"synopsis": "Command eitri-apispec regenerates docs/openapi.json from the api route table.",
"imports": [
"internal/server/api/spec"
]
},
{
"importPath": "cmd/eitri-oidc",
"plane": "binaries",
"synopsis": "eitri-oidc: the bundled OIDC issuer.",
"imports": [
"internal/oidcprovider",
"internal/version"
]
},
{
"importPath": "cmd/eitri-server",
"plane": "binaries",
"synopsis": "eitri-server: single-node control plane (no TLS termination here — front with a reverse proxy for TLS).",
"imports": [
"internal/server/boot",
"internal/version"
]
},
{
"importPath": "cmd/eitri-shape",
"plane": "binaries",
"synopsis": "eitri-shape regenerates the explorable architecture-shape diagram from the real package graph (`go list`).",
"imports": [
"internal/shape"
]
},
{
"importPath": "cmd/eitri-site",
"plane": "binaries",
"synopsis": "Command eitri-site generates the eitri.sh static site (default) or the release manifest (the \"manifest\" subcommand).",
"imports": [
"internal/site",
"internal/version"
]
},
{
"importPath": "cmd/eitri-smoke",
"plane": "binaries",
"synopsis": "eitri-smoke: the deploy boot-gate harness.",
"imports": [
"internal/smoke",
"internal/version"
]
},
{
"importPath": "internal/agent/bootstrap",
"plane": "data",
"synopsis": "Package bootstrap installs the agent's runtime — the cloud-hypervisor binary and its UEFI guest firmware (CLOUDHV.fd) — the first time it is missing on a host, by fetching sha-pinned artifacts from the eitri.sh release manifest (internal/relmanifest).",
"imports": [
"internal/relmanifest"
]
},
{
"importPath": "internal/agent/cloudhv",
"plane": "data",
"synopsis": "Package cloudhv manages one cloud-hypervisor process per VM.",
"imports": [
"internal/agent/exec",
"internal/agent/hostinfo",
"internal/agent/hyperlog",
"internal/agent/permanent",
"internal/agent/pidfile",
"internal/agent/state"
]
},
{
"importPath": "internal/agent/dhcp",
"plane": "data",
"synopsis": "Package dhcp is an in-process, reservation-only DHCPv4 responder for the eitri bridge.",
"imports": [
"internal/agent/ipalloc"
]
},
{
"importPath": "internal/agent/enrollclient",
"plane": "data",
"synopsis": "Package enrollclient speaks the control plane's enrollment endpoint.",
"imports": []
},
{
"importPath": "internal/agent/exec",
"plane": "data",
"synopsis": "Package exec defines the single command-runner type shared by the host-touching agent packages (cloudhv, imagecache, netenv).",
"imports": []
},
{
"importPath": "internal/agent/exposeproxy",
"plane": "data",
"synopsis": "Package exposeproxy publishes guest ports on their host.",
"imports": [
"internal/pb"
]
},
{
"importPath": "internal/agent/hostinfo",
"plane": "data",
"synopsis": "Package hostinfo gathers best-effort facts and live metrics about the fleet host the agent runs on.",
"imports": [
"internal/agent/exec",
"internal/pb"
]
},
{
"importPath": "internal/agent/hyperlog",
"plane": "data",
"synopsis": "Package hyperlog reads back the last thing a hypervisor said before it stopped running.",
"imports": []
},
{
"importPath": "internal/agent/imagecache",
"plane": "data",
"synopsis": "Package imagecache downloads and verifies content-addressed base images (decoded to raw in-process, LRU-evicted beyond MaxBytes).",
"imports": [
"internal/agent/permanent",
"internal/names"
]
},
{
"importPath": "internal/agent/ipalloc",
"plane": "data",
"synopsis": "Package ipalloc allocates VM IPs within the host's bridge CIDR.",
"imports": []
},
{
"importPath": "internal/agent/netenv",
"plane": "data",
"synopsis": "Package netenv manages the host side of VM networking: bridge eitri0 with the host as .1 gateway, per-VM taps, and NAT for outbound internet.",
"imports": [
"internal/agent/dhcp",
"internal/agent/exec",
"internal/agent/netsnoop",
"internal/agent/permanent",
"internal/agent/state"
]
},
{
"importPath": "internal/agent/netsnoop",
"plane": "data",
"synopsis": "Package netsnoop discovers the address a guest's named-network NIC was granted, by watching that NIC's own tap for its DHCP exchange.",
"imports": []
},
{
"importPath": "internal/agent/permanent",
"plane": "data",
"synopsis": "Package permanent mints agent errors that no retry can fix.",
"imports": []
},
{
"importPath": "internal/agent/pidfile",
"plane": "data",
"synopsis": "Package pidfile records which process a VM's guest runs as, in a form that survives a reboot without lying about it.",
"imports": []
},
{
"importPath": "internal/agent/reconcile",
"plane": "data",
"synopsis": "Package reconcile implements the agent's level-triggered reconcile loop.",
"imports": [
"internal/agent/permanent",
"internal/agent/seed",
"internal/agent/state",
"internal/pb",
"internal/version"
]
},
{
"importPath": "internal/agent/run",
"plane": "data",
"synopsis": "Package run implements the eitri-agent command line behind a tested RunCLI so cmd/eitri-agent stays thin wiring (arch R14).",
"imports": [
"internal/agent/bootstrap",
"internal/agent/cloudhv",
"internal/agent/enrollclient",
"internal/agent/exposeproxy",
"internal/agent/hostinfo",
"internal/agent/imagecache",
"internal/agent/netenv",
"internal/agent/reconcile",
"internal/agent/seed",
"internal/agent/serialpump",
"internal/agent/state",
"internal/agent/statelock",
"internal/agent/syncclient",
"internal/covsnap",
"internal/joinblob",
"internal/names",
"internal/version"
]
},
{
"importPath": "internal/agent/seed",
"plane": "data",
"synopsis": "Package seed builds the cloud-init NoCloud config-drive ISO (label CIDATA).",
"imports": [
"internal/cloudinit",
"internal/guest"
]
},
{
"importPath": "internal/agent/selfupdate",
"plane": "data",
"synopsis": "Package selfupdate replaces the running agent binary with a server-instructed release and re-execs.",
"imports": []
},
{
"importPath": "internal/agent/serialpump",
"plane": "data",
"synopsis": "Package serialpump owns the durability of VM serial consoles.",
"imports": []
},
{
"importPath": "internal/agent/state",
"plane": "data",
"synopsis": "Package state is the agent's durable state directory (default /var/lib/eitri-agent).",
"imports": [
"internal/names"
]
},
{
"importPath": "internal/agent/statelock",
"plane": "data",
"synopsis": "Package statelock enforces one running agent per identity.",
"imports": []
},
{
"importPath": "internal/agent/syncclient",
"plane": "data",
"synopsis": "Package syncclient holds the agent's stream loop: receive snapshots, run engine steps, send reports.",
"imports": [
"internal/agent/exec",
"internal/agent/hostinfo",
"internal/agent/reconcile",
"internal/agent/selfupdate",
"internal/agent/state",
"internal/pb",
"internal/transport",
"internal/version"
]
},
{
"importPath": "internal/agent/vfkit",
"plane": "data",
"synopsis": "Package vfkit manages one vfkit process per VM: the macOS backend, where vfkit is the signed helper that drives Apple's Virtualization.framework.",
"imports": [
"internal/agent/exec",
"internal/agent/hostinfo",
"internal/agent/hyperlog",
"internal/agent/permanent",
"internal/agent/pidfile",
"internal/agent/state"
]
},
{
"importPath": "internal/arch",
"plane": "tooling",
"synopsis": "Package arch holds executable architecture fitness functions for the Eitri module.",
"imports": []
},
{
"importPath": "internal/cli",
"plane": "tooling",
"synopsis": "Package cli implements the eitri client binary: self-signed short-lived SSH certs with the tenant's own user CA, host verification pinned to eitri's host CA, sessions through the system ssh, and tenant CA registration.",
"imports": [
"internal/guest",
"internal/names",
"internal/server/api/client"
]
},
{
"importPath": "internal/cloudinit",
"plane": "wire",
"synopsis": "Package cloudinit merges eitri's structured VM inputs into user-supplied cloud-init user-data.",
"imports": []
},
{
"importPath": "internal/covsnap",
"plane": "tooling",
"synopsis": "Package covsnap lets a long-running binary flush integration-coverage counters on demand.",
"imports": []
},
{
"importPath": "internal/gateclient",
"plane": "tooling",
"synopsis": "Package gateclient is a client of the eitri SSH-CA jump gate: it holds the credential cache (GateAuth) that self-signs short-lived user certs and verifies host certs against the eitri CA, and the two-hop dial (Dial) that reaches a VM by name through the gate.",
"imports": [
"internal/names"
]
},
{
"importPath": "internal/guest",
"plane": "wire",
"synopsis": "Package guest holds the handful of facts the control plane and the data plane must agree on about a guest VM.",
"imports": []
},
{
"importPath": "internal/joinblob",
"plane": "wire",
"synopsis": "Package joinblob encodes and decodes the single-paste enrollment token (\"join blob\") an agent uses to enroll: it carries the server's HTTP base URL, its QUIC address, a one-shot enrollment token, and the server's TLS cert fingerprint for out-of-band pinning.",
"imports": []
},
{
"importPath": "internal/mcpserver",
"plane": "tooling",
"synopsis": "Package mcpserver implements eitri's MCP toolset: tools that let a model create, control (SSH exec/files), and destroy eitri VMs.",
"imports": [
"internal/random",
"internal/server/api/client",
"internal/server/release"
]
},
{
"importPath": "internal/names",
"plane": "wire",
"synopsis": "Package names validates the DNS-label shape shared across planes: a VM's name doubles as its guest hostname, so it must be a valid RFC-1123 label.",
"imports": []
},
{
"importPath": "internal/oidcprovider",
"plane": "tooling",
"synopsis": "Package oidcprovider is a minimal, spec-compliant OIDC issuer: discovery, authorization-code + PKCE, token, and JWKS, with users in a flat file.",
"imports": []
},
{
"importPath": "internal/pb",
"plane": "wire",
"synopsis": "",
"imports": []
},
{
"importPath": "internal/random",
"plane": "wire",
"synopsis": "Package random provides small cryptographically-random helpers shared across the control plane, CLIs, and the integration harness — a leaf package so a CLI or test binary can reuse them without importing heavier deps (e.g.",
"imports": []
},
{
"importPath": "internal/relmanifest",
"plane": "wire",
"synopsis": "Package relmanifest is the eitri.sh release-manifest wire contract, shared by its producer (the site generator), the server (agent-upgrade offers), and the agent (runtime bootstrap).",
"imports": []
},
{
"importPath": "internal/server/api",
"plane": "control",
"synopsis": "Package api implements the admin REST API and the unauthenticated enrollment endpoint.",
"imports": [
"internal/cloudinit",
"internal/joinblob",
"internal/names",
"internal/random",
"internal/server/api/types",
"internal/server/delegation",
"internal/server/hosttoken",
"internal/server/hub",
"internal/server/registry",
"internal/server/release",
"internal/server/sshca",
"internal/server/store",
"internal/version"
]
},
{
"importPath": "internal/server/api/client",
"plane": "control",
"synopsis": "Package client is THE Go client for the eitri control-plane HTTP API — the one consumer every in-repo caller (MCP server, smoke gate, CLI) goes through.",
"imports": [
"internal/server/api/types"
]
},
{
"importPath": "internal/server/api/spec",
"plane": "control",
"synopsis": "Package spec projects the api route table into an OpenAPI 3.1 document.",
"imports": [
"internal/server/api",
"internal/server/api/types"
]
},
{
"importPath": "internal/server/api/types",
"plane": "control",
"synopsis": "Package types is the server HTTP API's wire contract: every request and response JSON shape the API speaks, and nothing else.",
"imports": []
},
{
"importPath": "internal/server/boot",
"plane": "control",
"synopsis": "Package boot implements the eitri-server command line behind a tested RunCLI so cmd/eitri-server stays thin wiring (arch R14).",
"imports": [
"internal/covsnap",
"internal/guest",
"internal/joinblob",
"internal/server/api",
"internal/server/config",
"internal/server/delegation",
"internal/server/health",
"internal/server/hub",
"internal/server/mcphttp",
"internal/server/registry",
"internal/server/release",
"internal/server/sshca",
"internal/server/sshgate",
"internal/server/store",
"internal/server/syncsvc",
"internal/server/vmssh",
"internal/server/web",
"internal/transport"
]
},
{
"importPath": "internal/server/config",
"plane": "control",
"synopsis": "Package config defines the eitri-server on-disk JSON configuration schema, loaded by the server binary (cmd/eitri-server) at startup.",
"imports": [
"internal/names"
]
},
{
"importPath": "internal/server/delegation",
"plane": "control",
"synopsis": "Package delegation holds the credentials a tenant has lent eitri.",
"imports": []
},
{
"importPath": "internal/server/health",
"plane": "control",
"synopsis": "Package health serves the eitri-server liveness and readiness probes.",
"imports": []
},
{
"importPath": "internal/server/hosttoken",
"plane": "control",
"synopsis": "Package hosttoken mints and verifies generation-versioned host credentials.",
"imports": []
},
{
"importPath": "internal/server/hub",
"plane": "control",
"synopsis": "Package hub wakes per-host QUIC streams when desired state changes.",
"imports": []
},
{
"importPath": "internal/server/mcphttp",
"plane": "control",
"synopsis": "Package mcphttp serves the eitri MCP toolset over HTTP at /mcp.",
"imports": [
"internal/mcpserver",
"internal/server/api",
"internal/server/api/client",
"internal/server/vmssh"
]
},
{
"importPath": "internal/server/registry",
"plane": "control",
"synopsis": "Package registry holds volatile actual state in memory.",
"imports": []
},
{
"importPath": "internal/server/release",
"plane": "control",
"synopsis": "Package release discovers the latest eitri release from a manifest URL (eitri.sh) and names the agent floors the control plane admits against.",
"imports": [
"internal/relmanifest",
"internal/version"
]
},
{
"importPath": "internal/server/seal",
"plane": "control",
"synopsis": "Package seal encrypts the key material eitri holds, so that what rests on disk is not what signs.",
"imports": []
},
{
"importPath": "internal/server/sshca",
"plane": "control",
"synopsis": "Package sshca manages eitri's SSH key material: a persistent user CA (whose short-lived certs authenticate admins to the jump gate and VMs) and a persistent gate host key.",
"imports": [
"internal/server/seal"
]
},
{
"importPath": "internal/server/sshgate",
"plane": "control",
"synopsis": "Package sshgate is eitri's hardened SSH jump gate: a bastion front-end that admins reach with `ssh -J gate ubuntu@\u003ctenant\u003e.\u003cvm\u003e`.",
"imports": []
},
{
"importPath": "internal/server/store",
"plane": "control",
"synopsis": "Package store is the server's durable control-plane state, backed by SQLite: the host registry, enrollment tokens, desired VM specs, and freed CIDRs.",
"imports": [
"internal/random",
"internal/transport"
]
},
{
"importPath": "internal/server/syncsvc",
"plane": "control",
"synopsis": "Package syncsvc is the QUIC server end of the agent reconcile stream.",
"imports": [
"internal/pb",
"internal/server/hosttoken",
"internal/server/hub",
"internal/server/registry",
"internal/server/release",
"internal/server/store",
"internal/transport"
]
},
{
"importPath": "internal/server/vmssh",
"plane": "control",
"synopsis": "Package vmssh reaches a tenant's VM from inside the control plane: it tunnels to the guest's sshd over the host's live sync connection and authenticates with the credential that tenant has delegated to eitri.",
"imports": [
"internal/names"
]
},
{
"importPath": "internal/server/web",
"plane": "control",
"synopsis": "Package web embeds the built SvelteKit single-page app and serves it with SPA-style fallback (unknown paths resolve to index.html for client routing).",
"imports": []
},
{
"importPath": "internal/shape",
"plane": "tooling",
"synopsis": "Package shape generates an explorable diagram of eitri's package graph from the real `go list` output, so the architecture view cannot silently drift from the code.",
"imports": []
},
{
"importPath": "internal/site",
"plane": "tooling",
"synopsis": "Package site generates the eitri.sh static site: docs/*.md and a markdown landing page rendered through one HTML template, plus the downloads page and the agent-upgrade release manifest.",
"imports": [
"internal/server/release"
]
},
{
"importPath": "internal/smoke",
"plane": "tooling",
"synopsis": "Package smoke is the deploy boot-gate harness.",
"imports": [
"internal/gateclient",
"internal/guest",
"internal/server/api/client"
]
},
{
"importPath": "internal/transport",
"plane": "wire",
"synopsis": "Package transport carries the agent↔server sync protocol over QUIC.",
"imports": []
},
{
"importPath": "internal/version",
"plane": "wire",
"synopsis": "Package version carries the build-stamped eitri version, set via -ldflags \"-X github.com/a73x/eitri/internal/version.Version=v0.0.2\".",
"imports": []
}
]
}