metis

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.

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:

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:

Watch the tutorial and introduction on YouTube

Versionierte Docker-Releases

Für produktive Installationen ist der versionierte Docker-Installer der empfohlene
Pfad. Er lädt ein unveränderliches Image aus GHCR, erstellt keine Git-Checkout-
Abhängigkeit und legt Daten sowie Workspace außerhalb des Containers ab.

curl -fsSL https://github.com/f1shyondrugs/metis/releases/latest/download/metis-docker-install.sh \\
  -o metis-docker-install.sh
bash metis-docker-install.sh --version latest

Für reproduzierbare Installationen kann ein konkreter Release-Tag verwendet werden:

bash metis-docker-install.sh --version v1.0.7

Ein Upgrade wird mit demselben Befehl und einer neuen Version ausgeführt. Die
Installationsdatei .metis-release.json, .env, das Datenverzeichnis und der
Workspace bleiben dabei erhalten; der Installer ersetzt nur den Image-Tag und
startet die Compose-Services mit docker compose pull und up -d neu.

One-line installer

The versioned Docker release installer above is recommended for production.
This legacy cross-platform bootstrap remains useful for development checkouts
or native installations. On Linux it installs native systemd; pass -- --docker
for Compose. On macOS and Windows it uses Docker when available; use --native /
-Native to keep the Node.js + launchd/Task Scheduler flow. The one-liner
downloads the platform installer to a temp file and executes that file — it does
not run the installer from a pipe.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/f1shyondrugs/metis/master/install.sh)"

Uninstall with the same bootstrap:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/f1shyondrugs/metis/master/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 --:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/f1shyondrugs/metis/master/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:

irm https://raw.githubusercontent.com/f1shyondrugs/metis/master/install.ps1 | iex

For a prompt-free Windows installation, download the platform script and pass
named arguments:

irm https://raw.githubusercontent.com/f1shyondrugs/metis/master/install/windows.ps1 -OutFile install.ps1
.\install.ps1 -NonInteractive -PasswordFile .\metis-password.txt

All three installers 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.

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.

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; complete account setup in the first-run UI. 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.

• Node.js 22+
• pnpm 9+
• A supported AI provider credential, unless you only want to explore the UI

1. Install

git clone https://github.com/f1shyondrugs/metis.git
cd metis-ai
pnpm install

2. Configure

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

pnpm dev

Open http://127.0.0.1:3100 and sign in with the
credentials from .env.

Docker Compose

With Docker and Compose installed, start the app, worker and MCP gateway with:

docker compose up --build

Published ports follow AI_CHAT_HOST or AI_CHAT_BIND in .env (default
127.0.0.1). Set either to 0.0.0.0 for LAN access, then apply with
./reload.sh in the install directory. docker compose restart keeps the old
bind address and environment.

When METIS_WORKSPACE is unset, Compose mounts ./workspace at /workspace.
Set METIS_WORKSPACE to use a different host workspace directory.

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:

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:

python3 -m pip install google-antigravity

The gateway lives behind the public module boundary in
packages/mcp-gateway. 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, docs/PRODUCTION-AUDIT.md,
and the gateway README.md before exposing any endpoint.

The complete example is in .env.example. The most useful
settings are:

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.

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.

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/.

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 for the reporting
process and deployment guidance.

Metis AI is released under the MIT License.