Metis AI

A private, extensible workspace for AI agents

Conversations, tools, terminals, browser sessions, memories, workspaces and MCP servers — brought together in one self-hosted application.

Repository · Issues · Contributing · Docs · Tutorial & Introduction

> Metis AI is designed for people who want an agent workspace they can run, > configure and extend themselves — without tying the entire experience to a > single model provider.

Why Metis AI?

Most AI interfaces stop at a chat transcript. Metis AI treats a conversation as a durable workspace. It combines the agent, its context, the tools it can use and the artifacts it creates in one private, self-hosted environment. ### Feature overview Metis AI includes the following capabilities: | Area | Capabilities | | --- | --- | | **Agent runtime** | Streaming responses, tool calls, thinking blocks, follow-up questions, run cancellation, resume support and durable chat history | | **Context and files** | Image and file uploads, previews, references, pinned context and model-aware context limits | | **Workspaces** | Plans, canvases, notes, memories, remote files and terminals available alongside a conversation | | **Browser control** | Authenticated browser sessions with tabs, navigation, forms, clicks, typing, scrolling, screenshots and viewport control | | **Voice input** | Speech transcription for composing messages | | **Provider freedom** | OpenAI, Anthropic, Google, xAI, OpenRouter, Cursor, Codex, Claude Code, Ollama, Vertex/ADC and generic OpenAI-compatible endpoints | | **MCP gateway** | Discover, register and call local or remote MCP servers, plus workflows, automations, web/documentation tools and platform integrations | | **Remote execution** | Enrolled remote clients with authenticated command execution, testing and file/workspace operations | | **Sharing and recovery** | Share chats and attachments through links, optionally protect them with a password, clone shared chats and revoke access | | **Administration** | Provider discovery and testing, model listing, preferences, status checks, recovery flows and configurable security boundaries | The Windows desktop Remote Client is maintained in the public [metis-remote-client repository](https://github.com/f1shyondrugs/metis-remote-client). Its installer and automatic updates come from that repository's GitHub Releases. Existing clients that still check their paired Metis server receive those public release files through an authenticated proxy. ### Tutorial & introduction The video walks through installation, provider setup, workspaces, notes, automations, browser control, voice input, sharing, agent modes, MCP servers, remote clients and memories:

Metis AI tutorial and introduction

[Watch the tutorial and introduction on YouTube](https://youtu.be/UhJVr7-CeOY)

Quick start

### One-line installer Metis installs natively on Linux, macOS, and Windows. Linux uses systemd; macOS and Windows use native background hosts. The bootstrap downloads the platform installer to a temporary file and executes it, preserving interactive input. ```bash /bin/bash -c "$(curl -fsSL https://github.com/f1shyondrugs/metis-ai/releases/latest/download/metis-install.sh)" ``` If an older native Linux install reports update status `127`, rerun the current installer once with that machine's existing installation directory (and its service name if customized). The old, already-running updater cannot acquire this PATH repair before its first successful update: ```bash /bin/bash -c "$(curl -fsSL https://github.com/f1shyondrugs/metis-ai/releases/latest/download/metis-install.sh)" -- \ --non-interactive --native --install-dir "/absolute/path/to/metis-ai" ``` This keeps `.env` and the data directory but replaces tracked local checkout changes with the selected upstream version. Native installs now save the Node and pnpm directories in `.env` for service starts and future updates. Uninstall with the same bootstrap: ```bash /bin/bash -c "$(curl -fsSL https://github.com/f1shyondrugs/metis-ai/releases/latest/download/metis-install.sh)" -- uninstall --yes --keep-data ``` The same command works on macOS and Linux. Do not use `curl | bash` against `linux.sh` or `macos.sh` directly. The default path never creates an account or asks for credentials. Start the app and create the first account in the first-run UI. For agents and CI, pass optional configuration flags after `--`: ```bash /bin/bash -c "$(curl -fsSL https://github.com/f1shyondrugs/metis-ai/releases/latest/download/metis-install.sh)" -- \ --non-interactive --port 3100 ``` Use `--help` for the available options. On Windows, the one-liner is a bootstrap without a `param()` block so `Invoke-Expression` is valid. It saves `windows.ps1` and invokes it with `-File`: ```powershell irm https://github.com/f1shyondrugs/metis-ai/releases/latest/download/metis-install.ps1 | iex ``` For a prompt-free Windows installation, download the platform script and pass named arguments: ```powershell irm https://raw.githubusercontent.com/f1shyondrugs/metis/master/install/windows.ps1 -OutFile install.ps1 .\install.ps1 -NonInteractive ``` During a normal interactive installation, every installer asks for the installation directory before it creates files or installs dependencies. Press Enter to accept `~/metis-ai`, or enter a different path. Root agents are enabled by default in Linux/macOS installations, with no extra flag or root prompt. The first-run UI offers the root OS user after the operator setup token is entered. Use `--deny-root-agents` to disable root execution; `--allow-root-agents` re-enables it on an existing installation. Upgrades preserve an existing explicit setting. Root agent workspaces must be inside the root user's home, and root execution remains limited to Host-Admins. All three installers also accept argument-only configuration for the install directory, data directory, agent workspace, ports, bind address, service name and public URL. Use `--help` on Linux/macOS or `-Help` on Windows for the complete list. Windows registers **Metis AI** in the Start menu and Installed Apps. A windowless host starts at sign-in, supervises the web app, worker and MCP gateway, and writes logs to the data directory. The Start menu entry opens the interface in your default browser. macOS installs a Finder/Spotlight app under `~/Applications`; launchd runs the native services in the background. Create your account in the browser; installer password arguments remain optional for automation. Both desktop installers check the effective web/MCP ports before installing dependencies or building, and again after restoring an existing configuration. A conflict reports the port and owning process; use `-Port` / `-McpPort` on Windows or `--port` / `--mcp-port` on macOS to choose free ports. Existing configuration is preserved on upgrade, so change its `.env` ports when needed. An unrelated HTTP 200 response is not accepted as Metis health. #### Non-interactive options The option names are intentionally listed side by side so the same deployment configuration can be reproduced on every supported operating system. Linux and macOS use Bash options; Windows uses PowerShell named parameters. | Purpose | Linux | macOS | Windows | Default | | --- | --- | --- | --- | --- | | Application checkout | `--install-dir DIR` | `--install-dir DIR` | `-InstallDir DIR` | `~/metis-ai` | | Runtime data directory | `--data-dir DIR` | `--data-dir DIR` | `-DataDir DIR` | `INSTALL_DIR/data` | | Agent workspace | `--agent-cwd DIR` | `--agent-cwd DIR` | `-AgentCwd DIR` | user home | | Web port | `--port PORT` | `--port PORT` | `-Port PORT` | `3100` | | Bind address | `--host HOST` | `--host HOST` | `-Host HOST` | `127.0.0.1` | | MCP gateway port | `--mcp-port PORT` | `--mcp-port PORT` | `-McpPort PORT` | `8787` | | Service/task name | `--service-name NAME` | `--service-name NAME` | `-ServiceName NAME` | `metis-ai` / `MetisAI` | | Public URL | `--public-url URL` | `--public-url URL` | `-PublicUrl URL` | `http://127.0.0.1:PORT` | | No prompts | `--non-interactive` | `--non-interactive` | `-NonInteractive` | off | | Native runtime | default | `--native` | `-Native` | every platform | | Allow root agents (Host-Admins only) | `--allow-root-agents` | `--allow-root-agents` | — | on | | Disable root agents (also on upgrade) | `--deny-root-agents` | `--deny-root-agents` | — | preserve current setting | | Dry run | `--dry-run` | `--dry-run` | `-DryRun` | off | | Skip runtime installation | — | — | `-SkipRuntimeInstall` | off | | Show help | `--help` or `-h` | `--help` or `-h` | `-Help` | — | For Linux and macOS, pass installer arguments after `--` to `/bin/bash -c "$(curl ...)"`. For PowerShell, download `install/windows.ps1` and invoke it with `-File`. `-SkipRuntimeInstall` only skips Windows' automatic Git/Node.js installation; it still verifies that the required tools are available. The installer uses safe defaults for machine-specific values and does not create the first user; read the operator token from `DATA_DIR/setup-token` locally and enter it in the first-run UI. The app creates this private file before listening. Review downloaded scripts before executing them in security-sensitive environments. The repository source can be overridden with `METIS_AI_REPO_URL`. The installers also ask whether the web application should be reachable on the local network. The secure default binds to `127.0.0.1`; choosing the network option binds to `0.0.0.0` and requires a firewall or trusted TLS reverse proxy. The scripts are hosted in the repository under `install/`; the website and Nginx configuration are not required for installation. Every installer writes an installation manifest and a matching uninstaller into the selected installation directory. Use `--keep-data` (or `-KeepData` on Windows) to remove services and application files while retaining chats, memories, uploads and encrypted provider credentials. Use `--dry-run` before removal when reviewing an existing installation.

Prerequisites

- Node.js 22+ - pnpm 9+ - A supported AI provider credential, unless you only want to explore the UI ### 1. Install ```bash git clone https://github.com/f1shyondrugs/metis.git cd metis-ai pnpm install ``` ### 2. Configure ```bash cp .env.example .env ``` Edit `.env` and set at least a login username/password. For provider credentials, configure connections later from **Settings → Providers**. Never commit `.env`. ### 3. Run the development server ```bash pnpm dev ``` Open [http://127.0.0.1:3100](http://127.0.0.1:3100) and sign in with the credentials from `.env`.
Production-style start ```bash pnpm build pnpm start ``` The custom server listens on `AI_CHAT_HOST` (default `127.0.0.1`) and defaults to port `3100`. Set `AI_CHAT_HOST=0.0.0.0` only when the app should be reachable on the local network, and put it behind an authenticated TLS reverse proxy before exposing it beyond a trusted LAN.
## Provider connections Provider connections are managed from **Settings → Providers**. Supported connection types include: - Cursor - OpenAI, Anthropic, Google Gemini and xAI/Grok - OpenRouter - Ollama and other local endpoints - Codex, Claude Code and supported Antigravity credentials - Generic OpenAI-compatible APIs such as Groq, DeepSeek, Mistral, Together, vLLM, LM Studio and LiteLLM API keys and supported account credential bundles are encrypted at rest and are not returned to the browser. Set `AI_CHAT_SECRETS_KEY` before saving a connection: ```bash openssl rand -hex 32 ``` The key must represent exactly 32 bytes: 64 hexadecimal characters or a 32-byte base64 value. Google Vertex/ADC connections additionally need a GCP project and configured Application Default Credentials. The optional Antigravity Python path needs: ```bash python3 -m pip install google-antigravity ```

MCP gateway

The gateway lives behind the public module boundary in [`packages/mcp-gateway`](./packages/mcp-gateway/README.md). It connects the agent runtime to registered local or remote MCP servers and supports discovery, workflows, web/documentation tools and selected platform integrations. For a trusted deployment: 1. Set a long, random `MCP_BEARER_TOKEN`. 2. Keep the gateway on localhost or place it behind a trusted authenticated proxy. 3. Set `AI_CHAT_ROOT`, `AI_CHAT_MCP_STATE_DIR` and `AGENT_CWD` explicitly. 4. Enable remote, optional or dangerous integrations only when you understand their permissions. 5. Treat shell, filesystem, Docker and service-control tools as privileged. See [`SECURITY.md`](./SECURITY.md), [`docs/PRODUCTION-AUDIT.md`](./docs/PRODUCTION-AUDIT.md), and the gateway [`README.md`](./packages/mcp-gateway/README.md) before exposing any endpoint.

Configuration

The complete example is in [`.env.example`](./.env.example). The most useful settings are: | Variable | Purpose | Default | | --- | --- | --- | | `PORT` | Web application port | `3100` | | `CHAT_USERNAME` / `CHAT_PASSWORD` | Application login | `admin` / required | | `CHAT_DATA_DIR` | SQLite database and runtime data directory | `./data` | | `AGENT_CWD` | Default working directory for agent tools | User home | | `AI_CHAT_SECRETS_KEY` | Encryption key for provider credentials | Unset | | `MCP_PORT` | MCP gateway port | `8787` | | `MCP_BEARER_TOKEN` | Gateway authentication token | Unset | | `MCP_ALLOW_REMOTE_ADMIN` | Allow remote administrative operations | `false` | | `MCP_ENABLE_REMOTE_SERVERS` | Enable remote MCP servers | `false` | | `MCP_ENABLE_OPTIONAL_SERVERS` | Enable optional integrations | `false` | | `MCP_LOCAL_SCRAPER_URL` | Local Scrapling fetch endpoint | `http://127.0.0.1:8890/fetch` | | `MCP_LOCAL_SEARCH_URL` | Optional SearXNG JSON endpoint tried before Scrapling search | `http://127.0.0.1:8888/search` | | `MCP_LOCAL_SCRAPER_SEARCH_URL` | Scrapling search fallback used when SearXNG is unavailable | `http://127.0.0.1:8890/search` | | `VOICE_TRANSCRIPTION_PRIVATE_BASE_URLS` | Host-admin allowlist for exact private/local voice-provider URL prefixes | Unset | Production installs should run the static-only Scrapling service from `deploy/systemd/metis-scraper.service.template`. SearXNG is optional: search uses SearXNG first, then the local Scrapling public-search parser, then the configured Exa child server. Page fetches use Scrapling first and Exa only for failed or incomplete public-page extraction. Interactive, authenticated, or challenge pages belong in the persistent browser instead.

Development

```bash pnpm dev # Start Next.js in development mode pnpm typecheck # TypeScript validation pnpm run test:providers # Provider adapter tests pnpm test # Provider and security tests pnpm lint # ESLint pnpm build # Production build ``` Before opening a pull request, run the checks that cover your change. The project's contribution expectations are documented in [`CONTRIBUTING.md`](./CONTRIBUTING.md).

Project layout

```text app/ Next.js routes, pages and API handlers components/ React UI and workspace panels docs/ Project documentation (start at docs/README.md) lib/ Agent runtime, providers, storage and MCP internals packages/mcp-gateway/ Public MCP gateway module boundary scripts/ Security and maintenance checks tests/ Provider-focused tests public/ Static assets and prompt data ``` Operator and architecture notes, including the current production audit, live in [`docs/`](./docs/README.md).

Security

Metis AI can execute powerful operations through agents and MCP servers. Do not expose a default installation directly to the public internet. Use strong secrets, a trusted proxy, least-privilege MCP configuration and isolated working directories. See [`SECURITY.md`](./SECURITY.md) for the reporting process and deployment guidance.

License

Metis AI is released under the [MIT License](./LICENSE).