The Self-hosted Daemon is for projects that need access to private infrastructure. If your project uses publicly accessible dependencies, use the cloud build environment instead - will auto-discover your lifecycle setup with no manual configuration needed.
ModelDaemon - Designed for Real Environments
The ModelDaemon runs directly inside your existing application environment - the same machine, the same runtime, the same network context your application already uses. There is no environment recreation, no containerization requirement, and no need to replicate your infrastructure elsewhere. This is intentional design. Enterprise applications depend on internal services, private registries, and runtime configurations that are difficult or impossible to faithfully reproduce on the public internet. ModelDaemon sidesteps that problem by sitting inside your network, where those services and credentials are already reachable — and it does so without polluting that environment with project-specific runtimes, because the agent and its dependencies live inside per-job isolated workspaces (see How It Works below). For teams with a stable internal network and a machine that can reach their private dependencies, ModelDaemon is the fastest and most reliable path to getting running.When to Use a Self-hosted Daemon
- Your app already builds and runs - no environment setup required
- Dependencies are already in place - language runtimes, package managers, internal tools
- You don’t need portability - the environment is stable and not going away
- Speed matters - you want ModelCode operational with minimal infrastructure changes
| Aspect | V1 | V2 |
|---|---|---|
| Where the AI agent runs | In cloud, sending shell commands back to the daemon | On the daemon host, inside per-job isolated workspaces |
| Project dependencies | You installed runtimes, package managers, and project tooling on the host yourself | The agent discovers them automatically and the daemon materializes them as isolated pixi environments per project |
| Workspace isolation | All jobs ran directly in your host shell | Each job runs in its own scratch directory under the daemon’s working tree, with its own pinned env versions |
| LLM provider keys | n/a — agent ran in cloud | The daemon proxies LLM traffic back through , so no provider API keys live on your host |
| Encryption key pair | You generated and uploaded a public key | Managed automatically by the daemon — nothing to configure |
| Lifecycle commands | You wrote install / build / run / health-check / test scripts manually | Auto-discovered by the agent from your codebase, the same way the cloud environment does |
| Environment variables | You added each variable in the UI before validation | Discovered alongside the lifecycle and editable later in the Lifecycle Setup page |
| End-to-end validation step | A separate “Validate Setup” wizard | Folded into normal lifecycle discovery and milestone runs |
How It Works
The ModelDaemon is a binary (mcode) that runs on a machine within your network. Once started, it:
- Registers with and begins sending periodic heartbeats
- Receives jobs from over an authenticated outbound connection — lifecycle discovery, spec extraction, milestone execution, code-review chat
- Spawns the morph-agent in an isolated workspace for each job — a fresh per-job scratch directory with its own pinned dependency environment
- Streams results, logs, and AI traffic back to through the same outbound connection
shell -c "command" invocation.
In V2, the AI morph-agent that drives migration work runs as a process on your daemon host. The daemon is responsible for setting up a clean, reproducible environment for it, executing it, and tearing everything down when the job finishes.
Per-job isolated workspaces
When dispatches a job, the daemon creates a fresh scratch directory under its working tree (<workdir>/jobs/<job-id>/) and starts a morph-agent HTTP server inside it. The agent operates on the repository clone in that directory, so jobs cannot see or interfere with each other’s files. When the job completes, the workspace and every process spawned inside it are cleaned up.
- Environment variables - Configure environment variables in the Modelcode UI, not via lifecycle commands.
- Working directory - The daemon manages the working directory and keeps it consistent across all commands within a single job. You don’t need to
cdinto the project directory unless a command should run in a nested directory. - Concatenated commands - When multiple commands must run in the same shell context, join them with
&&. - Private repositories - The daemon executes lifecycle commands exactly as defined. If Composer requires authentication for private repositories, those credentials must be present on the daemon host or supplied via encrypted environment variables.
The daemon process itself runs commands with the same permissions as the user that started
mcode. The agent runs inside its own pixi environment, so it does not inherit your host’s runtimes, but it does inherit network access, file-system permissions, and any credentials available to that user (SSH keys, kubeconfig, cloud-CLI tokens, etc.). Run the daemon as a user that has the network and credential access your project needs to reach private resources, and nothing more.Setting Up the Daemon
One daemon per project. Each project supports a single active ModelDaemon. If your team has multiple seats, only one person should set up the daemon for a given project - typically whoever owns or has access to the target environment. Other team members connect to the same project and share that daemon automatically. Setting up multiple daemons for the same project is not supported and will cause conflicts.
Prerequisites
- A machine on your network that can reach your private services
- A account with an active project
- Network connectivity from the machine to
*.modelcode.aiover HTTPS (outbound only — no inbound ports required) - A POSIX-compliant operating system (Linux or macOS)
Supported Operating Systems
- Linux (x86_64, ARM64) — Ubuntu, Debian, RHEL, Amazon Linux, SUSE, Alpine, and other POSIX-compatible distributions
- macOS (Intel & Apple Silicon)
- Windows — not currently supported
Onboarding Flow
The UI walks you through the full setup and generates the exact install command for your platform with your API key already filled in — follow the on-screen instructions. The flow boils down to three steps: name the daemon, run the generated install command on the daemon host, and click Verify & Continue so the platform confirms the daemon’s heartbeat.- Generate an API key - Creates credentials for the daemon to authenticate with
- Install the daemon - Download and install the
mcodebinary on your target machine - Set up encryption - Generate a key pair so the daemon can securely handle secrets
- Start the daemon - Run the daemon process and connect it to
- Verify the connection - Confirm the daemon is registered and online
- Configure lifecycle commands - Define the install, build, run, health check, and test commands for your project
- Configure environment variables - Add any variables your application needs at build or runtime, with optional secret encryption
- Validate the setup - Run an end-to-end validation that executes each lifecycle command in sequence
With a Self-hosted Daemon, lifecycle commands are configured at the project level during this onboarding flow. For the cloud environment, lifecycle configuration is also project-level but is auto-discovered - with separate origin and target entries, each containing scripts, variables, and a lifecycle document.
After Onboarding
Once the daemon is connected, dispatches a first job that does the following on your daemon host:- Materializes an isolated pixi environment based on the agent’s analysis of your codebase (manifests, lockfiles, framework conventions). On the very first project this also installs a shared pixi base layer; subsequent projects reuse it.
- Discovers the lifecycle configuration — install, build, run, health-check, and test scripts plus any environment variables — by reading the codebase and trying things in the isolated workspace. This is the same auto-discovery used for cloud projects.
- Surfaces the result in the UI. You can review and edit everything on the Lifecycle Setup page at any time.
Migrating from V1
V1 daemons are deprecated, but they have not been switched off:- Existing V1 projects keep working. If a project is already connected to a V1 daemon, that pairing continues to run jobs as before. There is no forced migration and no deadline you need to meet.
- New projects require V2. Any project created from now on can only connect to a V2 daemon. If you try to attach a new project to a V1 daemon, the connection will be rejected.
Why This Approach Works
Recreating an enterprise application environment from scratch is harder than it looks. Internal services have specific versions, configurations, and network paths that are rarely fully documented. Private registries require credentials that may be tied to specific machines or users. Runtime behavior often depends on system-level configuration that isn’t captured in source control. ModelDaemon avoids this entirely. It runs in your real environment - not a simulated one. The commands it executes are the same commands your developers run. The network paths it uses are the same ones your application uses in production. The credentials and config files are already in place. You get the correctness of an in-environment setup (real network, real credentials, real registries) without the operational cost of treating the host as part of the project’s runtime stack.Environment Stability
ModelDaemon is designed to run on a stable host. The environment where the daemon is installed should:- Remain accessible for the duration of the project
- Maintain consistent build and runtime behavior across sessions
- Not be decommissioned, re-imaged, or significantly reconfigured mid-project
Example: Running ModelDaemon in an Existing Application
A typical self-hosted daemon deployment looks like this:- The daemon binary is installed on the same server or VM where the application is already running
- The daemon is configured with an API key and pointed at the Modelcode platform
- Lifecycle commands - install, build, run, test - are defined in the Modelcode UI using the same commands the team already uses
- No infrastructure changes are made: no new VMs, no containers, no network modifications
- ModelCode begins executing build and test workflows immediately, using the existing environment
Troubleshooting
Daemon Shows as Offline
The daemon appears offline when has not received a heartbeat within the last few minutes. Check if the daemon process is running:mcode start.
Check network connectivity:
The daemon must be able to reach the server over HTTPS. Verify with:
mcode logs to show the most recent log lines. Logs are also written to the logs/ directory next to the mcode binary. Look for connection errors or authentication failures.
Common causes:
- The host rebooted and
mcode install-servicewas never run, so there is no service manager keeping the daemon up - A network change (VPN disconnect, firewall rule update) is blocking outbound HTTPS traffic
- The API key was rotated in the UI but not updated in the daemon’s
config.toml
Command Not Found
The daemon inherits thePATH from the shell that started it. When installed as a system service, it takes a snapshot of the current PATH and stores it in its config file. If you install new tools after the daemon is already running as a service, update the stored path with mcode refresh-path and restart the daemon.
API Key Issues
Test Generation Failed
Test generation failures occur when cannot generate tests for your project. This typically relates to the build or run steps. Application failed to build: Check the install and build command output in the validation logs. Common causes:- Missing dependencies that are only available on your private network
- Incorrect build command - verify it works when run manually on the same machine
- Environment variables missing - add them in the Modelcode UI
- Check that the port your application listens on is not already in use
- Verify that required services (databases, APIs) are reachable from the host machine
- Review the run command output for startup errors
- Verify the API key in the daemon’s
config.tomlmatches the one shown in the UI - If the key was rotated, update
config.tomland runmcode startagain
FAQ
Does the ModelDaemon Support Windows?
No. Windows is not currently supported.Do I need to install Python, Node, Java, or other runtimes on the host?
No. The agent declares each project’s dependencies in a manifest and the daemon installs them inside an isolated pixi environment under~/.local/share/modelcode/. Your host only needs to be able to reach the network locations your application reaches.
Where does the AI agent actually run?
On your daemon host, inside a per-job pixi-managed workspace. The daemon spawns onemorph-agent process per job, gives it an isolated working directory and pinned dependencies, and tears everything down when the job finishes. cloud orchestrates the work but does not execute it.
Do you store my code or my LLM provider keys in the cloud?
Source code is read by the agent on your daemon host and never copied off it as part of normal job execution. The daemon proxies the agent’s LLM calls through using your daemon’s API key, so there are no provider API keys (Anthropic, OpenAI, etc.) on the host.Can I run multiple daemons on the same machine?
No. The installer always writes to~/.local/share/modelcode/, so running it a second time on the same host (under the same user) replaces whatever daemon is already installed there — whether it’s a V1, an older V2, or a V2 registered under a different name. To run more than one daemon at the same time, install each on a separate machine.
Do I still need to configure lifecycle commands manually?
No. With a V2 daemon, the agent auto-discovers your lifecycle the same way it does for cloud projects. You can review and edit the discovered scripts and environment variables on the Lifecycle Setup page at any time.Do I still need to upload an encryption public key?
No. V2 daemons manage their encryption keys internally. There is nomcode encryption generate step and no public key field in the UI.
Does the ModelDaemon Support Windows?
Plan for ~5 GB under~/.local/share/modelcode/ for the daemon binary, pixi, and a small project’s environments. Larger monorepos or projects with many declared environments (e.g. one per service) will use more — pixi caches conda packages on disk, and the daemon keeps prior environment versions around as long as some workspace still pins them.
Next Steps
- Lifecycle Setup - How lifecycle configurations work for cloud projects
- Define Modernization Goals - Configure what your migration should achieve
- Reviewing the Project Spec - Review and approve your migration plan