Skip to main content
Glama
README.md
# 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.

TDQS

B3.4/5.0

Scored across 76 tools

Disambiguation3/5

The core resource families (services, databases, models, schedules, secrets, config) are separable, but the set has many near-parallel verbs: deploy vs deploy_app vs deploy_git vs deploy_template vs redeploy_service vs apply_project vs serve vs serve_model, plus service_logs/project_logs and diagnose_service/diagnose_project. The descriptions carry heavy explanatory load to keep these apart, which is exactly what overlap looks like — the agent must read a paragraph to pick correctly. Boundaries exist, but several (share_service vs add_domain vs add_hook, list_services vs list_models vs list_databases) require deliberate navigation.

Naming Consistency4/5

The dominant convention is snake_case verb_noun (list_services, create_database, set_secret, remove_schedule, run_schedule), applied consistently across most families. Deviations are mild: a handful of bare verbs (deploy, serve) and noun-first/domain-prefixed names (service_logs, service_stats, cluster_stats, proxy_status, system_disk, system_gc, capabilities, doctor). Readable throughout, but not the uniform pattern a 5 would require.

Tool Count2/5

76 tools is far past what an agent can hold in working context; any single concern (deploying an app) requires choosing among 5-8 candidates. The daemon's surface is genuinely broad (containers, DBs, AI gateway, proxy, schedules, audit), so not all of it is bloat, but the sheer size plus the redundancy in deploy/diagnose/log paths means many tools do not distinctly earn their place. Grouped or mode-parameterized tools would collapse this substantially.

Completeness4/5

Coverage is unusually deep: full lifecycle for services, databases, models, schedules, hooks, domains, secrets, variables, projects, config, audit and events, plus diagnostics, GC and health checks. Minor gaps are mostly deliberate (no database restore, no volume backup) and clearly documented with CLI fallbacks, so agents have a workaround rather than a dead end. A few asymmetric pairs remain — e.g. rich create/read for dumps but no delete, and no service config read-modify cycle shorter than get_app_config/set_app_config.

Maintenance

ActivityActive
ResponsivenessNo recent community issues