Local and cloud
Authentication and execution location are separate boundaries. You must sign in to use Agent Studio or Sapiom MCP, including their local authoring tools. After sign-in, the authoring loop starts on your machine and crosses into hosted infrastructure only when you link, deploy, run in production, or manage cloud state.
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. Invoking it through Agent Studio or Sapiom MCP requires Sapiom authentication, but the run makes no real Sapiom capability request and creates no Sapiom capability spend. 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 use hosted Sapiom infrastructure in addition to the authentication already required for authoring:
- 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 Sapiom MCP |
| Deploy and start a production run from the project | Agent Studio or Sapiom MCP |
| Inspect fleet and per-agent cloud state | Agents dashboard |
See Choose your path for the user-facing role of each surface.
© 2026 Sapiom, Inc.