StackShip has three distinct programmable surfaces today.
| Surface | Use it for | Authentication |
|---|---|---|
| OpenTofu native cloud | Planning, applying, locking, and state migration through /api/v2 |
OpenTofu OAuth or a scoped service-account token; managed attempts use an internal attempt credential |
| Native v1 REST API | The dashboard control plane | Authenticated session with an active organization |
| MCP server | Agent-operated reads and scoped writes over the v1 contract | OAuth 2.1 token bound to the MCP resource |
The separate StackShip CLI is a roadmap item and is not available in private
beta. Use tofu for infrastructure operations and the dashboard for human
control-plane work.
OpenTofu cloud protocol
StackShip implements the native cloud/TFE-compatible contract required by OpenTofu. It does not ask customers to configure the generic HTTP backend. OpenTofu resolves an organization and workspace through the standard cloud protocol, while StackShip independently authorizes the live credential and its tenant boundary.
Managed execution never receives the customer’s OAuth or
service-account credential. StackShip injects a separate opaque rat_
credential through TF_TOKEN_stackship_run for the exact active attempt. That
credential is not a customer API key: it cannot create runs, perform recovery,
or authenticate to MCP.
Supported execution versions are exact, not ranges: any stable OpenTofu
release from 1.6.0 up, including releases newer than the StackShip
deployment. GET /v1/toolchains/opentofu/versions lists the current upstream
stable releases and marks which already have an immutable toolchain pin.
Service discovery also advertises modules.v1, the standard module registry
protocol. tofu init resolves private modules from the
module registry with the same hostname-selected credential the
cloud contract already uses.
Native v1 API
The dashboard consumes the committed OpenAPI 3.1 contract through the generated
@stackship/api-client. JSON operations are exact-schema validated. Logs,
state, and run artifacts remain streams through the Worker boundary.
The v1 surface covers projects, workspaces, runs, review decisions, state history and downloads, workspace variables, audit inventory, policies, GitHub source settings, private module registry management, cloud credential profiles, and OpenTofu service accounts.
See v1 REST API for the exact path inventory and request rules.
MCP
The MCP server is OAuth protected and fails closed on issuer, signature,
expiry, audience, or scope mismatch. It publishes the full read catalog —
projects, workspaces, runs, review evidence, logs, state history, variables,
audit, policy, GitHub sources, the module registry, credential metadata, and
toolchains — to mcp:tools, and narrowly scoped write tools — run creation,
binding-exact approval and rejection, cancellation, workspace and variable
writes, policy attachment and soft override, and registry module lifecycle —
to tokens that additionally carry mcp:write. Destructive operations,
credential secrets, and step-up-gated downloads are not published and are
refused by the API for MCP credentials.
See MCP server for the complete catalog and rules.
Roadmap boundaries
The following roadmap capabilities are not available today:
- Roadmap: a StackShip-specific command-line binary, not available today;
- customer webhooks or general notification delivery;
- scheduled drift automation;
- customer-operated execution agents; and
- destructive MCP tools, including deletes, revocations, and apply recovery.