| name | sam-install-run |
| description | Use when someone wants to install or try Solace Agent Mesh on their own machine — downloading the desktop app or sam CLI, first chat with the built-in agents, running locally via Docker or `sam run --embedded`, or pre-flight checks for a local trial. Not for shared/team deployments (sam-deploy), building agents beyond the first chat (sam-author-agent), or fixing a broken installation (sam-troubleshoot). |
| version | dev |
sam-install-run
This skill gets one person from zero to chatting with SAM on their own machine. Deciding question: is anyone else depending on this instance? Yes → sam-deploy. Once they're chatting and want to build something → sam-author-agent.
Where everything comes from
All artifacts — desktop installers, the sam CLI binary, Docker image access, Helm charts — come from the Solace product portal: https://products.solace.com/prods/Agent_Mesh (login required). No portal access → Solace account team or solace.com/support.
- Never point users at GitHub (the product repos are not public).
- Never suggest
pip install solace-agent-mesh — that is the Python implementation, a different runtime. There is no pip route to this product.
The one hard prerequisite
An LLM API key (any OpenAI-compatible provider, or Anthropic). Everything else — broker, database, storage — is embedded/in-memory in all local trial modes. Don't have users stand up brokers, Postgres, or Kubernetes for a solo trial.
Paths, in order
- Desktop app — the default recommendation (macOS, Windows, Linux). Download from the portal, launch, supply the LLM key, chat. See references/trial-paths.md. Caveat: desktop installers are rolling out — if the portal doesn't show them yet, fall back to path 3 without apology.
- Local Docker — secondary. One
docker run of the all-in-one image. Good when the machine already lives in containers.
sam run --embedded — escape hatch for terminal-centric developers. Same runtime as the desktop app, in the user's terminal with all component logs in one stream. When a user says they live in the terminal, lead with this rather than upselling the desktop — the desktop gets one sentence as the default path, then respect their preference.
What first run actually looks like
No example gallery (yet). The chat UI opens with two pre-seeded agents:
- Orchestrator — the conversational entry point; chat with it immediately.
- Builder — the AI-assisted creation path: describe an agent in plain language and it drafts one. This is the bridge to
sam-author-agent.
Hard rules
- Go product only. No
pip install, no sam init (the Python scaffolding verb — the Go CLI has no scaffold verb; sam run --embedded boots from bundled defaults), no solace-ai-connector, no Python SAM ports/paths.
- Binary naming is not a user choice. The docs list base and
-enterprise binary filenames; use whichever the portal artifact ships — never present "base vs enterprise" as an edition decision (it isn't one; SAM is one product).
- The WebUI/gateway lands on port 8800 in embedded and Docker modes (startup log prints the URL — tell users to trust that line over any remembered port).
- Pre-flight on a laptop:
sam doctor with SAM_DOCTOR_CONTEXT=local checks the LLM key, ports, and runtime before first start — cheaper than debugging a blank chat.
- A failing trial (won't start, blank UI, LLM errors) routes to
sam-troubleshoot / sam-operate only after sam doctor has been run and read.
References
Graduation hand-offs: "now I want it to do X" → sam-author-agent (often just: talk to the Builder agent); "my team should use this" → sam-deploy (and sam config pull carries what they built — see sam-declarative-config).
The local/desktop instance runs a full platform whose config API is fronted by the gateway proxy (http://127.0.0.1:8800 by default), so sam config apply --url <that origin> targets it directly — you can iterate declarative config against the local instance, not just pull from it. See sam-declarative-config.
