Appliance quick start¶

Outcome: Install plasm-server, boot the control station (or headless mode), enable catalog APIs, provision an MCP key, and connect a client — then optionally use the plasm remote terminal against the same HTTP listener.

Install¶

From plasm.tools/get:

curl -fsSL https://plasm.tools/install/install.sh | bash

Appliance-only install:

curl -fsSL https://plasm.tools/install/install.sh | bash -s -- --product appliance

Default layout: ~/.plasm/appliance/ (postgres/, local/, plugins/). After install, plasm-server picks up {appliance}/plugins automatically.

From source (plasm-core checkout):

cargo build -p plasm-server --release
cargo run -p plasm --bin plasm-pack-plugins -- --apis-root apis --output-dir target/plasm-plugins
cargo run -p plasm-server --release -- --plugin-dir target/plasm-plugins

First boot¶

Interactive terminal (TTY on stdin and stdout):

plasm-server

Verify: Ratatui control station opens (Status tab shows HTTP/MCP listeners and Postgres).

Headless (CI, scripts, or non-TTY):

plasm-server --no-tui

Verify: stderr bootstrap milestones; curl -sS http://127.0.0.1:3000/v1/health → {"status":"ok"}.

Use --data-dir or PLASM_APPLIANCE_DIR only when you need a non-default state root. See Surface inventory for env overrides.

Enable APIs and MCP key¶

Use the control station (recommended):

APIs tab — filter (/), toggle catalogs (Space), save (s).
Keys tab — a add a label, Enter, then c copy the Bearer secret.
Clients tab — c copy Cursor MCP JSON (or p for a plasm profile).

Step-by-step with every shortcut: Control station (TUI).

CLI equivalent:

plasm-server mcp migrate-db   # only if bootstrap reported migrate errors
plasm-server mcp apis set github pokeapi
plasm-server mcp keys add --name cursor

Verify: MCP client connects with Authorization: Bearer <api_key> to /mcp (Streamable HTTP).

Credential planes (transport vs outbound): MCP & credentials. CLI tables: CLI reference.

Connect Cursor (example)¶

The Clients tab emits JSON like:

{
  "mcpServers": {
    "plasm": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Use streamableHttp transport per your MCP client’s schema.

Remote terminal against the appliance¶

In a project directory:

plasm init --server http://127.0.0.1:3000 --api-key "$PLASM_API_KEY"
plasm search "pokeapi pokemon"
plasm context -i "inspect pokemon" pokeapi:Pokemon
echo 'e1(p5=pikachu)[p5,p3]' | plasm run

Full flow: Remote terminal (plasm).

Next steps¶

Goal	Page
Install, TUI walkthrough (APIs, keys, clients)	Control station (TUI)
OAuth vs PAT, credential planes	MCP & credentials
`plasm-server mcp` / `oauth` commands	CLI reference
Author or pack catalogs	Catalog authoring