How Mellow fits together
Trace the app, local server, model services and execution boundaries.
In this topic
Mellow is the local agent workspace in Visca. A person starts a conversation, selects an agent and execution location, and decides which capabilities that agent may use. The application keeps the conversation, model requests, tool results, and approvals connected as the work progresses.
This map is for developers choosing an integration boundary. It describes the implementation rather than promising that every model, external service, or paired device is ready on a particular installation.
Start with the work, then choose an interface
| What you want to build | Entry point | What your integration owns |
|---|---|---|
| A custom chat client | Compatible HTTP chat API | Conversation history, rendering, cancellation, and client-side tools |
| A task for an existing Mellow agent | Agent run or dispatch API | Instructions, agent selection, task monitoring, and necessary approvals |
| A new capability | Native plugin or remote MCP connection | Tool schema, execution, errors, and dependency setup |
| Repeatable app setup | Declarative configuration | Desired state, previewing changes, and supplying credentials separately |
| Event-driven work | Schedules or folder watchers | Trigger scope, instructions, destination, and output policy |
A chat-completion request and an autonomous agent run are different contracts. A compatible chat endpoint can return a proposed function call. An agent run can execute the selected agent's permitted tools and continue with their results. Choose deliberately; do not assume that sending a tool schema grants host access.
Follow one task through the app
- Select context. The chat or API request identifies the agent, conversation, project or working folder, and model.
- Resolve capabilities. Mellow combines the agent's configuration with available tools, skills, memory, and applicable permissions.
- Request a model response. Local inference or a configured provider produces text and, where supported, structured tool calls.
- Execute authorized work. The agent loop validates arguments, applies policy, obtains approvals when needed, and records tool outcomes.
- Continue from evidence. Results return to the conversation before another model step. Completion, cancellation, and failure settle the task lifecycle.
- Keep useful continuity. Conversation storage and the separate memory pipeline retain the information enabled by the user's settings.
Understand the boundaries
The Mac is an execution location
Local model files, working folders, native permissions, and local tool processes belong to the host Mac. A paired client can interact with allowed host work, but the client does not automatically acquire unrestricted access to the host's files or identity. Pairing and a cloud login solve different problems.
A cloud workspace is a separate permission context
A Cloud workspace connection identifies an account and workspace through its server. Available agents and tasks depend on that workspace's services and permissions. A successful local model request does not demonstrate cloud readiness. Likewise, discovering workspace tools does not prove a published agent exists.
A provider is not a device
A provider supplies inference. A device runs work. A remote model may answer a chat whose tools execute locally; selecting a model therefore does not itself relocate the task. The selected execution destination must remain visible and unambiguous to the user.
Implementation map
| Area | Principal responsibility | Continue reading |
|---|---|---|
| HTTP handler | Route selection, authentication, body limits, request dispatch | API |
| Agent loop | Tool iteration, completion, clarification, cancellation | Agent execution |
| Model runtime | Loading, generation, concurrency, cache ownership | Inference runtime |
| Tool registry and envelopes | Discovery, authorization, executable tools, structured results | Tool contract |
| Memory services | Buffered writes, distillation, retrieval, consolidation | Memory internals |
| Identity and secure channel | Key scope, validation, revocation, protected remote calls | Identity internals |
| Sandbox manager | Guest lifecycle, agent isolation, host bridge | Sandbox |
| Configuration service | Export, schema, plan, apply | Configuration |
Diagnose the right layer
For a failed task, establish whether the request reached Mellow, resolved a model, produced a tool call, passed policy, executed, and returned a final response. Capture the first failing boundary. Replacing a model will not repair a denied folder permission; reconnecting a workspace will not repair a local model bundle. Insights helps connect these events without treating a healthy server as proof that the entire task succeeded.
Continue exploring · Build with MellowHTTP API →Discover models, call inference endpoints or choose the agent execution lifecycle.