How Local-First Works in Apprentice

Apprentice is local-first software for running AI agents from your desktop. It is not a hosted SaaS where Triple Bits runs your agents for you.

Local-first means the app, agent configuration, runtime decisions, logs, memory, tasks, schedules, permissions, budgets, and audit history are coordinated locally on your machine.

It does not mean every model call is local. Model traffic follows the provider or local runtime you choose for each agent.

The Short Version

Apprentice runs on your computer.

Your agents run through a Docker-backed local runtime.

Your app data is stored locally.

Your model calls go to the provider you configure.

That means:

• If you use Ollama, LM Studio, or Docker Model Runner, model calls can stay local.
• If you use OpenAI, Anthropic, Gemini, DeepSeek, Mistral, Kimi, GLM, Qwen, Claude Code, Codex, Gemini CLI, or ChatGPT Subscription, that provider receives the prompt and context needed for the model call.
• Triple Bits does not need to host your agent runtime for the core Apprentice workflow.

What Stays Local

Apprentice stores application data on your machine.

This includes:

• Agent configuration.
• Agent instructions.
• Provider settings.
• Runtime decisions.
• Tasks.
• Schedules.
• Memory.
• Knowledge metadata.
• Logs.
• Activity history.
• Permission decisions.
• Budget state.
• Audit history.
• Local SQLite database state.

Production data is stored in your operating system's application data directory:

• Windows: %APPDATA%\apprentice\
• macOS: ~/Library/Application Support/apprentice/
• Linux: ~/.local/share/apprentice/

Development builds use the project .devdata/ directory instead.

What May Leave Your Machine

Model traffic depends on the provider.

If an agent uses a cloud API, CLI provider, or subscription provider, Apprentice sends the prompt and relevant context to that provider so the model can respond.

Examples:

• OpenAI API requests go to OpenAI.
• Anthropic / Claude API requests go to Anthropic.
• Google Gemini API requests go to Google.
• Claude Code, Codex, and Gemini CLI use their configured CLI authentication paths.
• ChatGPT Subscription uses the configured ChatGPT subscription path.

If you want model calls to stay local, choose a local runtime and local model that you have configured on your machine.

Docker-Backed Agent Execution

Docker is required because Apprentice uses it as part of the agent runtime boundary.

Agents do not run commands directly on your host machine. They run through a controlled Linux environment managed by Apprentice.

This gives agents a bounded place to work:

• Agent-specific runtime context.
• Configured filesystem access.
• Mounted folders only when you add them.
• Read-only or read-write volume choices.
• Permission checks before sensitive operations.
• Command and website allow/block controls when configured.

Docker is not the AI model provider. Docker is the execution environment. The provider is still chosen separately.

Folder Access Is Explicit

Agents do not automatically get broad access to your filesystem.

If an agent needs a project folder, add that folder as a volume during agent setup or later in the agent configuration.

Use read-only access when the agent only needs to inspect files. Use read-write access only when you want the agent to modify files.

This is one of the most important local-first habits in Apprentice: give each agent the smallest useful workspace first, then expand only when needed.

The Backend Owns Runtime Decisions

In Apprentice, the backend owns runtime decisions.

The frontend shows settings, accepts user intent, and renders state. It does not decide execution policy by itself.

The backend validates and coordinates things like:

• Effective runtime configuration.
• Provider and account resolution.
• Permission decisions.
• Guardrail inputs.
• Queue and scheduling behavior.
• MCP runtime configuration.
• Container setup.
• Timeout policy.
• Rate-limit handling.
• Audit events.

This matters because runtime behavior should be consistent and inspectable, not scattered across UI-only logic.

Credentials

Provider credentials and integration credentials are stored locally using the available credential storage for your operating system where supported.

For local runtimes, credentials may not be required.

For cloud, CLI, and subscription providers, you bring your own provider account, API key, OAuth login, or CLI authentication.

Apprentice does not resell model tokens and does not act as a hosted model proxy.

Memory And Knowledge

Apprentice supports local agent memory and uploaded knowledge files.

Memory, knowledge metadata, and related agent state are part of local Apprentice data. Knowledge files are associated with the agent that uses them.

Model calls can still include relevant memory or knowledge context when the selected provider needs it to answer. If that provider is external, the relevant prompt context is sent to that provider.

MCP Tools And Integrations

MCP tools and integrations are configured locally in Apprentice, but each tool or integration has its own behavior.

For example:

• A local MCP server may run only on your machine.
• An external MCP server may call an external service.
• A messaging integration may send and receive messages through that messaging platform.
• A webhook is, by nature, network-facing.

Local-first means Apprentice coordinates these tools locally and records the agent-side state locally. It does not mean every connected service is offline or local.

What Local-First Does Not Mean

Local-first does not mean:

• Apprentice is local-model-only.
• Cloud providers receive no prompt context.
• Docker is optional.
• Agents can access every file automatically.
• External MCP tools or integrations are automatically private.
• Apprentice is a hosted multi-user agent cloud.

The accurate rule is:

App data and runtime control are local. Model and tool traffic follow the providers, runtimes, MCP tools, and integrations you configure.

Practical First-Agent Setup

For your first agent:

1. Use one provider and one model.
2. Use Ask for Approval permissions.
3. Mount one folder only if the agent needs it.
4. Prefer read-only access at first.
5. Keep the system prompt narrow.
6. Run one test message.
7. Review what the agent did before expanding access.

That gives you the local-first workflow Apprentice is designed for: configure an agent, run it inside a bounded local runtime, inspect the result, then adjust the boundaries.

Next Step

After you understand local-first execution, run and review your first agent before expanding its permissions or adding more capabilities.