Local and cloud
Sapiom’s authoring loop starts locally and crosses into the cloud when you choose to link, deploy, or run in production. The boundary is action-specific: the local authoring MCP can perform account-free project work and authenticated cloud lifecycle operations.
Local work
Section titled “Local work”Your agent source, sapiom.json, and local capability stubs live in the agent project. Agent Studio and its coding-agent sessions run on your machine.
These authoring operations stay local:
- scaffold or edit an agent project;
- type-check and validate its step graph;
- run the project with local capability stubs.
A Local Run executes your real step code but replaces Sapiom capability calls with stubs. It does not require Sapiom authentication and does not spend on paid capabilities. A passing local run proves the local graph and your chosen stub responses worked; it does not prove that a provider will return the same data in production.
Local Run does not fetch a deployed definition’s cloud secrets. Author code is still ordinary local code, so it inherits the launching process’s environment and retains its own filesystem and network effects.
The cloud boundary
Section titled “The cloud boundary”These operations require a Sapiom account and use Sapiom cloud:
- Link resolves or creates the hosted agent associated with the project.
- Deploy bundles the project’s current local source, including uncommitted source reachable from
index.ts, pushes a synthesized build tree, and starts a cloud build. - Prod Run starts a real run of the hosted agent’s active ready version.
- Inspect, signal, and schedule read or change cloud runs and triggers.
Deploy is asynchronous and can consume metered cloud build compute. A successful deploy leaves a ready build that future production runs can use. An agent that follows latest uses its newest ready build; an explicitly pinned agent continues using the selected ready build until the pin is cleared. Every production run records the exact build it started with, so a later deploy cannot rewrite a run already in flight.
Production step code uses the runtime-provided ctx.sapiom client. Those calls reach real capabilities and can incur usage charges. The runtime supplies a tenant-scoped credential to the agent; do not put an API key in the project or in sapiom.json.
Definition-scoped secrets are resolved for each production step dispatch. Non-secret runtime defaults are assembled into entry input for supported customer run starts. See Configure authentication and runtime inputs before moving credentials or defaults across this boundary.
Where cloud state appears
Section titled “Where cloud state appears”The Agents area of the Sapiom dashboard shows organization-owned agents and their builds, versions, runs, alerts, and per-agent settings. It operates hosted state; it is not a browser code editor for the local project.
| If you want to… | Use |
|---|---|
| Edit source or test against stubs | Agent Studio or the local authoring MCP |
| Deploy and start a production run from the project | Agent Studio or the local authoring MCP |
| Inspect fleet and per-agent cloud state | Agents dashboard |
| Make a one-off capability call | Hosted MCP or @sapiom/tools |
The hosted MCP also exposes cloud agent lifecycle tools for clients that cannot work from a local checkout. It remains a direct-access reference surface, not an additional local Getting Started path.
See Studio, MCP, SDK, and dashboard for the responsibility of each surface.
© 2026 Sapiom, Inc.