# mittwald — Deployment Guide for AI Agents

> How to deploy a full-stack JavaScript application to mittwald, end to end, without a human in the loop (one API token must be provisioned by a human once). mittwald is a managed hosting and container platform operated from Germany; all infrastructure is GDPR-compliant.

## 1. Authentication

One credential drives everything (API, CLI, headless MCP):

- Obtain an API token: mStudio UI → user profile → API tokens, or programmatically
  `POST https://api.mittwald.de/v2/users/self/api-tokens/` (requires an existing token).
- A lost token cannot be recovered; store it securely.
- Export it for the CLI and scripts:

    export MITTWALD_API_TOKEN=<token>

- Direct API calls accept either header:

    Authorization: Bearer <token>
    X-Access-Token: <token>

API base URL: `https://api.mittwald.de/v2/`

## 2. CLI

    npm install -g @mittwald/cli        # any OS
    # or: brew tap mittwald/cli && brew install mw

The command is `mw`. With `MITTWALD_API_TOKEN` set, every command works non-interactively.
Discover commands and flags with `mw --help` and `mw <topic> --help`.
Useful entry points: `mw project list`, `mw app create node --help`.

## 3. MCP server

Remote MCP server (HTTP transport), nothing to install:

    https://mcp.mittwald.de/mcp

Claude Code:

    claude mcp add --transport http mittwald https://mcp.mittwald.de/mcp

Generic client config:

    { "mcpServers": { "mittwald": { "type": "http", "url": "https://mcp.mittwald.de/mcp" } } }

Auth: OAuth 2.1 with PKCE (interactive clients; browser login, revocable scoped tokens).
For CI/headless environments authenticate with an API token instead.
Capabilities include managing projects, apps, containers, and databases in natural language.

## 4. Deploying a Node.js app

General model: a Node.js app on mittwald is a directory plus a start command.

1. Create the app (CLI, MCP, or mStudio). Node.js apps get a target directory on the host.
2. Build locally or in CI.
3. Transfer build output into the app directory via rsync, SFTP, or git.
4. Set the start command for the app.
5. IMPORTANT: apps do NOT restart automatically when files change. Trigger a restart
   explicitly (mStudio, CLI, or MCP) after every deployment.

Example (TanStack Start):

    vite build                                       # produces .output/
    rsync -az .output/ <ssh-user>@<ssh-host>:<app-dir>/
    # app start command: node .output/server/index.mjs
    # then restart the app

## 5. Framework recipes

### TanStack Start
- Nitro's `node-server` preset is the default — no config needed.
- Build: `vite build` → `.output/`
- Start command: `node .output/server/index.mjs`

### Next.js
- Set `output: "standalone"` in `next.config`.
- Build: `next build`
- Start command: `node .next/standalone/server.js`
- Also deploy static assets: copy `.next/static` to `.next/standalone/.next/static`
  and `public/` to `.next/standalone/public`.

### Astro (SSR)
- Use adapter `@astrojs/node` with `mode: "standalone"`.
- Build: `astro build`
- Start command: `node ./dist/server/entry.mjs`
- Fully static Astro sites need no Node app at all — deploy `dist/` as static files.

## 6. Alternative deployment paths

- GitHub Action: "mittwald mStudio container deployment" (GitHub Marketplace) for container workloads.
- Terraform: `mittwald/terraform-provider-mittwald` — infrastructure as code; requires an API key.
- Git Deploy Extension (mStudio): webhook-triggered transfer of a Git repository into an app on every push.
- SDKs for custom tooling: PHP, JavaScript/Node.js (`@mittwald/api-client`), Go.

## 7. Error recovery hints

- 401/403 from the API: token missing, expired, or lacking permissions — verify the
  `Authorization` header and token scope.
- App serves stale code after deploy: the app was not restarted (see section 4, step 5).
- CLI behaves interactively in CI: ensure `MITTWALD_API_TOKEN` is exported in the environment.

## Reference

- Developer portal: https://developer.mittwald.de/
- API intro: https://developer.mittwald.de/docs/v2/api/intro/
- CLI docs: https://developer.mittwald.de/docs/v2/cli/
- Node.js apps: https://developer.mittwald.de/docs/v2/platform/workloads/nodejs/
- MCP server: https://developer.mittwald.de/de/docs/v2/mcp/
- GitHub: https://github.com/mittwald