eigent/docs/get_started/self-hosting.md

title	description	icon
Self-hosting	Run Eigent with your own backend, model providers, and local workspace.	server

Self-host Eigent when you need control over model providers, credentials, project files, or the infrastructure that runs your agents. A self-hosted installation uses the open-source Eigent application and lets you connect cloud APIs, OpenAI-compatible endpoints, or local inference servers.

This page describes the recommended setup path. Exact deployment requirements can change between releases, so use the repository files and release notes as the source of truth for version-specific values.

Before you begin

Prepare the following:

• A supported desktop operating system or Linux development environment
• Git
• Node.js 18 through 22
• The Python version required by the repository backend
• Enough disk space for dependencies, generated files, and optional local models
• Credentials for at least one cloud provider, or a running local model server

Local model requirements depend on the model and runtime. Large models can require substantial memory or GPU capacity.

Choose a deployment model

Eigent supports three common arrangements:

Arrangement	Model execution	Best for
Managed application	Eigent Cloud	Fast evaluation with minimal setup
Self-hosted with BYOK	External provider APIs	Infrastructure control with hosted model quality
Fully local	Ollama, vLLM, SGLang, LM Studio, or LLaMA.cpp	Private environments and local experimentation

You can configure more than one provider and change the preferred model later.

Set up the repository

1. Clone the Eigent repository:

   git clone https://github.com/eigent-ai/eigent.git
   cd eigent
   

2. Install the frontend dependencies:

   npm install
   

3. Review .env.development, backend/README.md, and the root README.md for the current backend and environment configuration.

4. Start the development application:

   npm run dev
   

5. In Eigent, open Agents > Models and configure a model provider.

The first development start can take longer because Eigent prepares frontend and backend dependencies.

Screenshot placeholder: Add a screenshot of Eigent running locally with Agents > Models open. Crop the image to the application window and hide credentials.

Configure a model

For the fastest self-hosted setup, connect an existing provider:

1. In Eigent, open Agents > Models.
2. Expand Bring Your Own Key.
3. Select a provider.
4. Enter the API key, endpoint, and model name required by that provider.
5. Select Validate or Save.
6. Enable the provider and mark it as preferred when you want it to be the default.

To keep inference local, start one of the supported runtimes and follow Local models.

Configure tools and browser access

A model can reason about a task, but tools let it act.

• Add hosted integrations from MCP Marketplace.
• Add your own local or remote server from Custom MCP servers.
• Configure a CDP browser from Browser connections.
• Create a Space from a local folder when agents need direct access to project files.

Video placeholder: Add a 60-90 second MP4 showing a local installation, model configuration, local-folder Space creation, and the first successful task. Include captions and a short transcript.

Build a distributable application

Use the build script for the target platform:

npm run build

Platform-specific scripts include:

npm run build:mac
npm run build:win
npm run build:linux

Review the Electron signing, packaging, and backend dependency requirements before distributing a build to other users.

Update a self-hosted installation

1. Commit or back up local configuration changes.
2. Pull the target release or branch.
3. Review release notes and environment changes.
4. Reinstall dependencies when lockfiles changed.
5. Run the relevant tests and build command.
6. Start Eigent and validate models, connectors, browser sessions, and existing Spaces.

Troubleshooting

The application starts without a model

Open Agents > Models and configure at least one cloud, BYOK, or local provider. Eigent blocks new tasks when no valid model is available.

A local model cannot be reached

Confirm that the runtime is running, the endpoint includes the expected /v1 path, and the port is accessible from the Eigent process.

MCP tools fail during startup

Review the MCP command, arguments, environment variables, and executable path. Run the server independently to confirm that it starts before adding it to Eigent.

Browser connection fails

Confirm that Chrome or Chromium was started with remote debugging and that the configured port exposes /json/version.

Next steps

Compare every cloud and local model provider supported by Eigent. Review the repository architecture and extension points. Understand how the frontend, Brain backend, and services work together.