# Nerdit

**A self-hosted PaaS for your own machine, built so an AI agent can run it.**

Point Nerdit at a folder or a Git repository: it builds the app, runs it as a
supervised service, gives it a URL, and wires it to a database or a local
model when it needs one. You drive it from the `nerdit` CLI, the local
dashboard, or an AI agent through its MCP server. The agent gets the same
operations as the CLI, behind scoped tokens and an audit log.

```bash
nerdit deploy ./my-app --wait       # build, run, wait until healthy
nerdit serve llama3.1:8b --gpus 1   # local model behind an OpenAI-compatible API
```

Your apps, data and models stay on your hardware. The optional
[Nerdit Cloud](#nerdit-cloud) account adds remote access and hosted URLs, but
it doesn't run your apps. An unlinked machine keeps working on its own.

**Free during the public beta**, with up to five linked machines per account.

## How it works

One daemon, `nerditd`, runs on your machine next to Docker:

```
  nerdit CLI ───┐                 ┌─ apps (Docker, health-checked, restarted)
  dashboard ────┼─ REST ► nerditd ┼─ models (Ollama / vLLM, or an external API)
  AI agent (MCP)┘                 ├─ databases (Postgres, Redis)
                                  └─ Caddy: URLs + TLS
```

An app says what it needs in a `nerdit.toml` next to its code:

```toml
[deploy]
name = "my-app"
port = 8000

[ai.default]
provider = "ollama"      # or "api" for an external endpoint
model = "llama3.1:8b"
```

The app starts with `OPENAI_BASE_URL` and `OPENAI_API_KEY` set. To move from a
local model to a hosted API, you change the config. The app code stays the
same.

## Install

```bash
curl -fsSL https://get.nerdit.ai | sh
nerdit doctor
```

This installs one signed archive: the CLI, the daemon and a pinned Caddy. You
don't need Python. It also registers a service and starts the daemon. You need
Docker installed and running. The dashboard is at `http://127.0.0.1:9321/`.

For your first deployment, see the
[quickstart](https://docs.nerdit.ai/engine/quickstart).
[Other install methods](#other-install-methods) are listed below.

## Use it with an AI agent

Nerdit ships an MCP server with 59 tools. Your agent can deploy, wire and
diagnose apps without a shell.

### Claude Code, Cursor and other local clients (stdio)

On the machine where `nerdit` is installed:

```bash
claude mcp add nerdit -- nerdit mcp
```

Other clients take the equivalent entry:

```json
{
  "mcpServers": {
    "nerdit": { "command": "nerdit", "args": ["mcp"] }
  }
}
```

If your client doesn't inherit your shell's `PATH`, use an absolute path to
`nerdit`.

The server acts with the credentials of your `nerdit` CLI. Give an agent a
narrow token rather than your admin one:

```bash
nerdit token create --role submitter --scope my-app --expires-in 24h
```

The `readonly` role can list and read but not write. A token scoped to a
service can only change that service. See
[Security](https://docs.nerdit.ai/engine/security) for how the CLI selects a
token.

### Claude on the web or desktop (remote, through Nerdit Cloud)

Link the machine with `nerdit link`. Then open **Agents** in
[app.nerdit.ai](https://app.nerdit.ai) and add the connection URL it shows as a
custom connector in Claude. You approve which machines or projects the
agent can reach. No token leaves your machine. See the
[guide](https://docs.nerdit.ai/app/connect-assistant).

### Over HTTP

Set `[mcp].http_enabled = true` to serve the same tools at
`http://127.0.0.1:9321/api/mcp`, behind a bearer token. See
[MCP setup](https://docs.nerdit.ai/engine/mcp).

### What to ask

> Deploy the app in `./todo-api`, give it a Postgres database, and tell me the
> URL once it's healthy.

> `blog` is crash-looping. Find out why and fix it.

> Serve `qwen2.5:7b` and point `my-chatbot` at it instead of the OpenAI API.

A typical run: `capabilities` → `deploy` (with `dry_run` first) →
`wait_for_service` → `diagnose_service` and `service_logs` if something fails.
An agent that has no files on the machine can use `write_app_files`, then
`deploy_app`. It can also use `deploy_git`.

The API is built for agents to retry safely:

- Every write is **idempotent**, so a retry never runs an action twice.
- Every write is **audited**.
- Errors carry a stable `code` and a recovery `hint`.
- Reads are **bounded**, so no single call floods the context window.
- Secrets are **write-only**: an agent can set them but never read them back.

## What you get

- **Deploy** from a folder, a Git URL or a template, using a Dockerfile or the
  Python or Node buildpacks. Images are versioned, and deploys support
  `--dry-run`, `--wait` and `--rollback`.
- **Services** restart with backoff and have HTTP and TCP health checks and
  stable ports. A redeploy cuts over with no downtime.
- **URLs and TLS** come from an embedded Caddy. It routes by path or
  subdomain, serves your own domains, advertises over mDNS on the LAN, and uses
  an internal CA that you can pin.
- **Models** run through Ollama or vLLM on your GPU, or through an external
  API. Apps get the same environment variables either way.
- **Databases**: managed Postgres and Redis. Nerdit creates the credentials
  and binds them into apps through `[db.*]`.
- **Projects** group several services in one `nerdit.toml` (`nerdit apply`).
  Variables are plain or secret. Secrets are encrypted at rest and can be
  rotated.
- **Backups** cover the control plane, with an offline restore. A managed
  database also gets a logical dump (`nerdit db dump`) that you can restore
  while it runs.

## Other install methods

**pip.** Needs Python 3.11+ and Docker, on Linux, macOS, or Windows through
WSL2:

```bash
python3 -m venv ~/.venvs/nerdit && source ~/.venvs/nerdit/bin/activate
python -m pip install nerdit
nerdit init && nerdit doctor
```

The CLI, the daemon, the dashboard, MCP and mDNS are all included. The pip
package doesn't bundle Caddy or register a startup service. Install Caddy
yourself if you want HTTPS, and run `nerdit init` again after a reboot. See
[installation](https://docs.nerdit.ai/engine/installation#install-with-pip).

**From source.**

```bash
git clone https://github.com/nerdit-ai/nerdit && cd nerdit
python -m venv venv && venv/bin/pip install -e ".[dev,mcp]"
(cd src/nerdit/daemon/web && npm ci && npm run build)   # dashboard, required
venv/bin/nerdit init
```

## Platforms

- **Linux**: Ubuntu 22.04 or 24.04, with systemd.
- **macOS**: Apple Silicon. Models run on the CPU.
- **Windows**: through WSL2 only.
- **GPUs**: NVIDIA needs Linux or WSL2. AMD support is experimental and behind a
  flag.

## No telemetry

The daemon collects no product telemetry. Linking to Nerdit Cloud, public relay
traffic and external AI APIs send only the data their feature needs. The
optional `[posthog]` dashboard analytics hook is off by default and reports to
your own PostHog project.

## Nerdit Cloud

[app.nerdit.ai](https://app.nerdit.ai) adds:

- remote access and assistant connections
- deploys from GitHub
- hosted URLs

Your machine connects out to the cloud, so you open no inbound port. Hosted
shares are private by default: only you and the people you allow in the Nerdit
App can open them. Public access needs an explicit publication and follows the
[Terms](https://nerdit.ai/terms).

Questions or feedback: [feedback@nerdit.ai](mailto:feedback@nerdit.ai).

## License

Apache-2.0, see [LICENSE](LICENSE). "Nerdit" and the logo are trademarks and
are not covered by the code license, see [NOTICE](NOTICE).

## Contributing

Issues and pull requests are welcome. [CONTRIBUTING.md](CONTRIBUTING.md)
explains how contributions land in releases.