Nerdit
OfficialManages URLs and TLS through an embedded Caddy server, allowing agents to route services by path or subdomain, serve custom domains, and advertise over mDNS.
Deploys and manages applications as Docker containers with health checks, restarts, and versioned images.
Enables deploying applications directly from a Git repository URL.
Enables deploying applications from GitHub repositories.
Runs and manages local AI models through Ollama, exposing them via an OpenAI-compatible API.
Integrates with external AI APIs like OpenAI, allowing apps to use hosted models through a consistent environment.
Provides managed Redis databases, creating credentials and binding them into applications.
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.
nerdit deploy ./my-app --wait # build, run, wait until healthy
nerdit serve llama3.1:8b --gpus 1 # local model behind an OpenAI-compatible APIYour apps, data and models stay on your hardware. The optional 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 + TLSAn app says what it needs in a nerdit.toml next to its code:
[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.
Related MCP server: emergent-mcp
Install
curl -fsSL https://get.nerdit.ai | sh
nerdit doctorThis 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. 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:
claude mcp add nerdit -- nerdit mcpOther clients take the equivalent entry:
{
"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:
nerdit token create --role submitter --scope my-app --expires-in 24hThe readonly role can list and read but not write. A token scoped to a
service can only change that service. See
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 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.
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.
What to ask
Deploy the app in
./todo-api, give it a Postgres database, and tell me the URL once it's healthy.
blogis crash-looping. Find out why and fix it.
Serve
qwen2.5:7band pointmy-chatbotat 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
codeand a recoveryhint.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,--waitand--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:
python3 -m venv ~/.venvs/nerdit && source ~/.venvs/nerdit/bin/activate
python -m pip install nerdit
nerdit init && nerdit doctorThe 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.
From source.
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 initPlatforms
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 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.
Questions or feedback: feedback@nerdit.ai.
License
Apache-2.0, see LICENSE. "Nerdit" and the logo are trademarks and are not covered by the code license, see NOTICE.
Contributing
Issues and pull requests are welcome. CONTRIBUTING.md explains how contributions land in releases.
Available Tools
76 toolsadd_domainA
Serve a deployed app at a domain YOU own, from this node's own proxy (P26).
Unlike ``share_service`` (Nerdit's domain, over the cloud tunnel), this
is the node's embedded Caddy answering ``https://<domain>/`` directly —
in either proxy mode, at the ROOT, so a frontend needs no ``/<app>/``
base path. The one thing the daemon cannot do for you: point the
domain's DNS (A/AAAA/CNAME) at this machine. By default the domain is
served with the node's internal CA, so a client must run
``nerdit trust`` once. ``acme=True`` requests a public ACME
certificate; it needs an ADMIN token (403 ``domain.acme_forbidden``,
``reason: acme_admin_only`` — the node has one ACME account whose rate
limits every domain on it shares) and 409 ``domain.acme_disabled``
unless the daemon has ``[proxy.acme].enabled``.
Refusals:
422 ``domain.invalid`` — the name broke exactly one grammar rule and the
message names it (``empty``, ``whitespace``, ``not_bare``,
``has_port``, ``wildcard``, ``ip_literal``, ``idn``, ``single_label``,
``grammar``, ``reserved``); 409 ``domain.taken`` (one domain, one
service — never silently re-pointed); 422 ``domain.kind_unsupported``
(models and databases are not routed).
Returns ``{domain, url, state, cert_state, created}``; ``state`` is
``ready`` | ``withheld`` (``withheld`` = the proxy is off, the app is
not routed yet, or its ``[deploy].edge_auth`` secret does not resolve —
the row is stored either way and answers once it is). ``cert_state`` is
the orthogonal certificate fact: ``internal`` (this node's CA) |
``disabled`` (``acme`` asked for, ``[proxy.acme]`` off) | ``pending``
(issuing, or failing — check ``doctor``) | ``issued`` | ``expired``.
The URL then appears in ``get_service`` / ``list_routes`` under
``public_urls`` (kind ``domain``).
Inputs: name (required), domain (required), acme, idempotency_key.
add_hookA
Give a deployed app an inbound webhook address a provider can POST to.
The machine verifies each delivery's signature before the app sees it,
then POSTs the provider's headers and exact body to ``path``. No secret
travels through this tool: the response carries ``url`` (paste it at the
provider) and ``secret_key``; then store the provider's signing secret
with ``set_secret(name, {secret_key: value})``. ``url`` is null until
the machine is linked, and answers only once the app is shared.
Refusals: 422 ``hook.invalid`` (``reason`` ``name`` or ``shape``), 422
``hook.kind_unsupported`` (models and databases), 409 ``hook.exists``
(a different webhook already has that name). A replay of the same
webhook answers ``created: false``.
Inputs: name (required), path (required), sender (required), hook_name (required), +3 more.
add_scheduleA
Have this machine POST to a deployed app's path on a timer (cron).
Each due minute the daemon POSTs ``{}`` to the running app with headers
``X-Nerdit-Schedule`` (the name), ``X-Nerdit-Schedule-Run`` (the run id)
and ``X-Nerdit-Schedule-Token``: the app must compare that token, in
constant time, with its ``NERDIT_SCHEDULE_TOKEN`` env var and refuse a
mismatch. Answer ``202`` and work from your own queue for long jobs.
No retry, no overlap (a run still out makes the next ``skipped_overlap``),
one catch-up run after downtime under 24 h. Upsert by name: the same
name with new fields updates it. At most 10 per app.
Refusals: 422 ``schedule.cron_invalid`` / ``schedule.too_frequent`` /
``schedule.path_invalid`` / ``schedule.timezone_unknown`` /
``schedule.name_invalid`` / ``schedule.kind_unsupported``; 409
``schedule.limit_reached``; 409 ``schedule.restart_required`` (the app
was launched by an older daemon: restart it once). Returns
``{schedule, created}``.
Inputs: cron (required), name (required), path (required), schedule_name (required), +3 more.
apply_configA
Declaratively apply a multi-section daemon config document (all-or-nothing).
A dry run needs neither an ``If-Match`` nor an idempotency key.
Inputs: sections (required), dry_run, if_match, idempotency_key.
apply_projectA
Apply a project's declaration: deploy every [services.<name>] of its nerdit.toml.
The loop: ``get_project`` (read) → ``apply_project(dry_run=true)`` →
if ``status`` is ``waiting_for_variables``, do NOT invent or request
the values in chat: ask the human to run ``nerdit vars set <project>
--secret --prompt KEY`` for each name in ``missing``, then dry-run
again → ``apply_project`` → ``wait_for_service`` once per ``label`` in
``services`` → ``diagnose_service`` on any that failed.
The response lists ``services`` in declaration order, each with its
``label`` (the name every other tool takes: ``web`` is the project
name, any other service ``<service>--<project>``), ``action``
(``fresh``/``redeploy``) and, on a dry run, its ``plan`` (env key names
only, values never); ``public_urls`` carries every advertised address.
``waiting_for_variables`` deploys nothing and returns names only.
Asynchronous like every deploy: ``applied`` means accepted, not healthy.
Every refusal lands before the first build, and a dry run creates
nothing and mints no idempotency key. A project another token owns is
409 ``project.owned``. There is NO rollback across services: a failure
on one is ``project.apply_incomplete``, whose ``services`` lists the
ones already applied and ``failed`` the one that was not — fix it and
apply again (done services redeploy, the rest are retried). A
``[deploy]``-only ``nerdit.toml`` is not a declaration: use
``deploy_app`` / ``deploy_git`` for it (they answer 422
``deploy.use_apply`` on a declaration).
SANDBOX: by DEFAULT containers run with all Linux capabilities dropped
(``cap_drop=["ALL"]``) and no-new-privileges — both are operator settings
(``[containers].drop_all_caps`` / ``[containers].no_new_privileges``), so
read the live profile in ``capabilities.sandbox`` rather than assuming: an
operator may have relaxed it. Under that default, an image whose entrypoint
does root work — ``chown``/``chmod`` of its own runtime dirs, dropping
privileges via ``setuid``/``setgid``, writing ``/var/run`` — dies before
your app ever starts. Stock ``nginx`` is the classic trap. Use a non-root
image and a non-root ``USER`` that owns the files it writes: for a static
site, ``nginxinc/nginx-unprivileged`` (listens on **8080**, so set
``port=8080``) or any tiny static server. A crash from this reports
remediation code ``image_needs_privileges`` in ``diagnose_service``. PORT
CONTRACT: the container MUST listen on the declared ``port`` (the tool
argument, else ``nerdit.toml`` ``[deploy].port``, else **8000**) — that is
the only port the daemon publishes and health-checks, so listening anywhere
else fails the health probe with a healthy-looking container. A port below
1024 is NOT the reason a root entrypoint is needed: every container runs on
the docker bridge in its own network namespace (never host networking),
where Docker sets ``net.ipv4.ip_unprivileged_port_start=0``, so binding 80
needs no capability and no root — the chown/setuid work does.
Inputs: project (required), ref, dry_run, repo_url, +2 more.
capabilitiesA
Describe this daemon: version, caller role/quotas, URL grammar, backends.
Role-aware, pure in-memory read — call it first to learn what the
daemon can do (buildpacks, model backends, proxy mode and public-URL
shape, deploy limits, git allowlist, feature flags) instead of probing
endpoints. Admin callers additionally receive ``proxy.admin_addr`` and
the ``paths`` block.
Inputs: no named parameters.
cluster_statsB
Get aggregate cluster metrics (GPUs in use/total, services up).
Inputs: no named parameters.
create_databaseA
Provision a managed database (kind=database workload).
Provisioning is asynchronous: the call returns immediately with the
database row in ``building`` while the daemon pulls the image off-tick
and launches the server; poll ``list_databases`` (or ``get_service``)
until ``db_ready`` is true. Lifecycle (stop / restart / delete) goes
through the existing service tools.
The daemon mints the password server-side and stores it write-only — it
is NEVER returned by this tool (key names only). An app connects to this
database by declaring a ``[db.<name>]`` binding (``provider="managed"``,
``database`` = this database's name — the ``database`` field is
required, there is no implicit default); at each launch it receives
``NERDIT_DB_<NAME>_URL``, and the ``default`` binding also sets
``DATABASE_URL`` (Postgres) or ``REDIS_URL`` (Redis) with the composed
DSN so an unmodified client library connects with no code change.
Inputs: name, backend, idempotency_key.
create_projectA
Create an empty project, reserving its name for your token.
A project groups one app's services, the models and databases they
reference, and their public addresses. The name is reserved for the
token that created it: another token's deploy, ``serve_model`` or
``create_database`` of that name is refused with 409 ``project.owned``
(an admin bypasses), and the project remains after ``remove_service``
until ``delete_project`` releases it. You rarely need this before a
deploy — every deployed app already becomes a project of its own name —
but it lets you hold a name ahead of the first deploy. A name another
token already reserved through ``set_secret`` is 409
``service.name_claimed``; a name in use is 409 ``project.exists``.
Inputs: name (required), idempotency_key.
delete_projectA
Delete a project: every service in it, then the row, releasing the name.
Services go one by one through the same cascade as ``remove_service``
(owner-or-admin each; a dependency guard or an in-flight run refuses a
service exactly as there). The project row goes last and only when
every service went: a refusal leaves the project in place with 409
``project.delete_incomplete`` listing ``deleted`` and ``failed``, and
re-running after the fix is idempotent. Owner or admin only.
Inputs: name (required), purge, idempotency_key.
deployA
Use when: the source is a local folder. Asynchronous — follow with wait_for_service.
Deploys that folder (build + run + URL), or rolls back with
``rollback=True``. The response carries ``next_step`` — a machine-shaped
``{tool, args, why}`` naming the very call to make next — because a 201
here means "the build was accepted", never "the app is up".
``path`` is read by the process serving this tool, so it works only on
the local ``nerdit mcp`` process; on a remote/HTTP connection it is
refused with ``mcp.local_path_unavailable``. Use ``write_app_files`` +
``deploy_app`` there, or ``deploy_git`` / ``deploy_template``.
``rollback=True`` needs no path and works over either transport.
If the app's ``nerdit.toml`` declares ``[ai.*]`` bindings, each is
injected at launch as ``NERDIT_AI_<NAME>_URL/_KEY/_MODEL``, and the
``default`` binding also sets ``OPENAI_BASE_URL/OPENAI_API_KEY/
OPENAI_MODEL`` — point the app's OpenAI SDK at these; no code change
needed. ``dry_run=True``
returns the build/config plan diff (env key names only, values never).
``nerdit.toml`` ``[deploy]`` keys — anything else is IGNORED and
reported back in the response ``hints``: ``name``, ``port``, ``gpus``,
``start``, ``health``, ``health_type`` (``http``|``tcp``),
``memory_limit``, ``cpu_limit``, ``volumes``, ``release``, ``cutover``,
``auto_deploy``, ``edge_auth``, ``forward_authorization``, ``build_settings``.
Generated Node builds run
``scripts.build`` automatically;
override it through ``[deploy.build_settings]`` or use a Dockerfile.
``release`` runs once inside the new image before traffic moves; if it
fails the deploy settles ``failed`` and the image reverts, never the data —
whatever the migration already committed stays, so write idempotent
migrations. ``cutover`` null = zero-downtime swap
when eligible, false = same-port swap.
On a successful non-dry-run deploy the
response carries ``summary`` (app/status/version/public_url; ``summary.public_url`` is the
preferred address: trusted domain, then hosted, then local), ``hints``
(ordered one-liners, never empty) and ``next_step`` (the structured
follow-up call); a ``dry_run`` plan and a ``rollback`` response carry
none of the three — read a plan's advisories from its ``warnings``. On a
node in ``path`` proxy mode the local URL serves the app at ``/<name>/``,
so a frontend reached there must be built with that base path (never for
a hosted or domain URL, which serve at the root; the hint is omitted when
one exists); in ``subdomain`` mode it is served at the root of its own
hostname and needs none — read ``capabilities.proxy.mode``.
``build_settings`` overrides
preset/install/build/start/node_version/package_manager/subdir/public_env.
``preset`` selects node/nextjs/python/dockerfile; null resets to
repository/default detection.
An existing Dockerfile retains precedence.
Omit it to preserve saved overrides; a null field resets to repository/default,
and ``build: false`` skips compilation.
``public_env`` passes public build-time variables (shown in clear in a dry
run; secret references are refused). Secret mounts are unsupported;
runtime env is unchanged.
SANDBOX: by DEFAULT containers run with all Linux capabilities dropped
(``cap_drop=["ALL"]``) and no-new-privileges — both are operator settings
(``[containers].drop_all_caps`` / ``[containers].no_new_privileges``), so
read the live profile in ``capabilities.sandbox`` rather than assuming: an
operator may have relaxed it. Under that default, an image whose entrypoint
does root work — ``chown``/``chmod`` of its own runtime dirs, dropping
privileges via ``setuid``/``setgid``, writing ``/var/run`` — dies before
your app ever starts. Stock ``nginx`` is the classic trap. Use a non-root
image and a non-root ``USER`` that owns the files it writes: for a static
site, ``nginxinc/nginx-unprivileged`` (listens on **8080**, so set
``port=8080``) or any tiny static server. A crash from this reports
remediation code ``image_needs_privileges`` in ``diagnose_service``. PORT
CONTRACT: the container MUST listen on the declared ``port`` (the tool
argument, else ``nerdit.toml`` ``[deploy].port``, else **8000**) — that is
the only port the daemon publishes and health-checks, so listening anywhere
else fails the health probe with a healthy-looking container. A port below
1024 is NOT the reason a root entrypoint is needed: every container runs on
the docker bridge in its own network namespace (never host networking),
where Docker sets ``net.ipv4.ip_unprivileged_port_start=0``, so binding 80
needs no capability and no root — the chown/setuid work does.
Inputs: env, gpus, name, path, +8 more.
deploy_appA
Use when: you used write_app_files. Asynchronous — follow with wait_for_service.
Distinct from ``deploy`` (which uploads a folder from the machine the MCP
server runs on) and from ``deploy_git`` (which clones a repository): this
one deploys the workspace of the same name, so it is the deploy verb for
an app you wrote in this conversation. Call it again after each
``write_app_files`` to ship an edit — ``redeploy_service`` refuses
workspace apps by design and points back here.
If the workspace's ``nerdit.toml`` declares ``[ai.*]`` bindings, each is
injected at launch as ``NERDIT_AI_<NAME>_URL/_KEY/_MODEL``, and the
``default`` binding also sets ``OPENAI_BASE_URL/OPENAI_API_KEY/
OPENAI_MODEL``. A dry run returns the build/config plan diff with env key
names only, values never, and mints no idempotency key.
``nerdit.toml`` ``[deploy]`` keys — anything else is IGNORED and
reported back in the response ``hints``: ``name``, ``port``, ``gpus``,
``start``, ``health``, ``health_type`` (``http``|``tcp``),
``memory_limit``, ``cpu_limit``, ``volumes``, ``release``, ``cutover``,
``auto_deploy``, ``edge_auth``, ``forward_authorization``, ``build_settings``.
Use ``[deploy.build_settings]``
for build overrides, or a Dockerfile for custom builds.
``release`` runs once inside the new image before traffic moves; if it
fails the deploy settles ``failed`` and the image reverts, never the data —
whatever the migration already committed stays, so write idempotent
migrations. ``cutover`` null = zero-downtime swap
when eligible, false = same-port swap. An ``env`` value that is exactly
``${secrets[.shared].KEY}`` or ``${vars[.shared].KEY}`` resolves at launch
(unset: 422 ``deploy.env_ref_unresolved``; embedded in text: 422
``deploy.invalid``); other values are literal. ``set_secret`` /
``nerdit secrets set`` still injects at launch and overrides an ``env``
key of the same name.
On a successful non-dry-run deploy the
response carries ``summary`` (app/status/version/public_url; ``summary.public_url`` is the
preferred address: trusted domain, then hosted, then local), ``hints``
(ordered one-liners, never empty) and ``next_step`` (the structured
follow-up call); a ``dry_run`` plan carries none of the three — read a
plan's advisories from its ``warnings``. On a node in ``path``
proxy mode the local URL serves the app at ``/<name>/``, so a frontend
reached there must be built with that base path; hosted and domain URLs
serve at the root and never need one.
``build_settings`` overrides
preset/install/build/start/node_version/package_manager/subdir/public_env.
``preset`` selects node/nextjs/python/dockerfile; null resets to
repository/default detection.
An existing Dockerfile retains precedence.
Omit it to preserve saved overrides; a null field resets to repository/default,
and ``build: false`` skips compilation. Commands run inside the build container.
``public_env`` passes public build-time variables (shown in clear in a dry
run; secret references are refused). Secret mounts are unsupported;
runtime env is unchanged.
SANDBOX: by DEFAULT containers run with all Linux capabilities dropped
(``cap_drop=["ALL"]``) and no-new-privileges — both are operator settings
(``[containers].drop_all_caps`` / ``[containers].no_new_privileges``), so
read the live profile in ``capabilities.sandbox`` rather than assuming: an
operator may have relaxed it. Under that default, an image whose entrypoint
does root work — ``chown``/``chmod`` of its own runtime dirs, dropping
privileges via ``setuid``/``setgid``, writing ``/var/run`` — dies before
your app ever starts. Stock ``nginx`` is the classic trap. Use a non-root
image and a non-root ``USER`` that owns the files it writes: for a static
site, ``nginxinc/nginx-unprivileged`` (listens on **8080**, so set
``port=8080``) or any tiny static server. A crash from this reports
remediation code ``image_needs_privileges`` in ``diagnose_service``. PORT
CONTRACT: the container MUST listen on the declared ``port`` (the tool
argument, else ``nerdit.toml`` ``[deploy].port``, else **8000**) — that is
the only port the daemon publishes and health-checks, so listening anywhere
else fails the health probe with a healthy-looking container. A port below
1024 is NOT the reason a root entrypoint is needed: every container runs on
the docker bridge in its own network namespace (never host networking),
where Docker sets ``net.ipv4.ip_unprivileged_port_start=0``, so binding 80
needs no capability and no root — the chown/setuid work does.
Inputs: name (required), env, gpus, port, +6 more.
deploy_gitA
Use when: the app lives in a Git repo. Asynchronous — follow with wait_for_service.
Clones ``repo_url`` server-side (public GitHub by default), then builds
and runs it like ``deploy``. The token reference is resolved server-side
— a raw credential never passes through the tool.
``dry_run=True`` returns the build/config plan diff (env key names only,
values never).
If the repo's ``nerdit.toml`` declares ``[ai.*]`` bindings, each is
injected at launch as ``NERDIT_AI_<NAME>_URL/_KEY/_MODEL``, and the
``default`` binding also sets ``OPENAI_BASE_URL/OPENAI_API_KEY/
OPENAI_MODEL`` — point the app's OpenAI SDK at these; no code change
needed.
``nerdit.toml`` ``[deploy]`` keys — anything else is IGNORED and
reported back in the response ``hints``: ``name``, ``port``, ``gpus``,
``start``, ``health``, ``health_type`` (``http``|``tcp``),
``memory_limit``, ``cpu_limit``, ``volumes``, ``release``, ``cutover``,
``auto_deploy``, ``edge_auth``, ``forward_authorization``, ``build_settings``.
Generated Node builds run
``scripts.build`` automatically;
override it through ``[deploy.build_settings]`` or use a Dockerfile.
``release`` runs once inside the new image before traffic moves; if it
fails the deploy settles ``failed`` and the image reverts, never the data —
whatever the migration already committed stays, so write idempotent
migrations. ``cutover`` null = zero-downtime swap
when eligible, false = same-port swap.
On a successful non-dry-run deploy the
response carries ``summary`` (app/status/version/public_url; ``summary.public_url`` is the
preferred address: trusted domain, then hosted, then local), ``hints``
(ordered one-liners, never empty) and ``next_step`` (the structured
follow-up call); a ``dry_run`` plan carries none of the three — read a
plan's advisories from its ``warnings``. On a node in ``path``
proxy mode the local URL serves the app at ``/<name>/``, so a frontend
reached there must be built with that base path; hosted and domain URLs
serve at the root and never need one.
``build_settings`` overrides
preset/install/build/start/node_version/package_manager/subdir/public_env.
``preset`` selects node/nextjs/python/dockerfile; null resets to
repository/default detection.
An existing Dockerfile retains precedence.
Omit it to preserve saved overrides; a null field resets to repository/default,
and ``build: false`` skips compilation.
``public_env`` passes public build-time variables (shown in clear in a dry
run; secret references are refused). Secret mounts are unsupported;
runtime env is unchanged.
SANDBOX: by DEFAULT containers run with all Linux capabilities dropped
(``cap_drop=["ALL"]``) and no-new-privileges — both are operator settings
(``[containers].drop_all_caps`` / ``[containers].no_new_privileges``), so
read the live profile in ``capabilities.sandbox`` rather than assuming: an
operator may have relaxed it. Under that default, an image whose entrypoint
does root work — ``chown``/``chmod`` of its own runtime dirs, dropping
privileges via ``setuid``/``setgid``, writing ``/var/run`` — dies before
your app ever starts. Stock ``nginx`` is the classic trap. Use a non-root
image and a non-root ``USER`` that owns the files it writes: for a static
site, ``nginxinc/nginx-unprivileged`` (listens on **8080**, so set
``port=8080``) or any tiny static server. A crash from this reports
remediation code ``image_needs_privileges`` in ``diagnose_service``. PORT
CONTRACT: the container MUST listen on the declared ``port`` (the tool
argument, else ``nerdit.toml`` ``[deploy].port``, else **8000**) — that is
the only port the daemon publishes and health-checks, so listening anywhere
else fails the health probe with a healthy-looking container. A port below
1024 is NOT the reason a root entrypoint is needed: every container runs on
the docker bridge in its own network namespace (never host networking),
where Docker sets ``net.ipv4.ip_unprivileged_port_start=0``, so binding 80
needs no capability and no root — the chown/setuid work does.
Inputs: name (required), repo_url (required), env, ref, +10 more.
deploy_templateA
Use when: you want a starter app. Asynchronous — follow with wait_for_service.
Resolves ``template_id`` (see ``list_app_templates``), clones its
catalog repo server-side, and deploys it under ``name``. ``env`` and the
deploy overrides layer over the template's defaults.
The response carries ``summary``, ``hints``
(never empty) and ``next_step`` — the structured follow-up call — since
a 201 here means the build was accepted, not that the app is up.
An existing Dockerfile retains precedence over ``build_settings``.
Omission preserves overrides; a null field resets to repository/default.
``dry_run=True`` previews without writes,
building or storing secrets. ``public_env`` passes public build-time
variables (shown in clear in a dry run; secret references are refused);
secret mounts are unsupported.
If the template declares ``[ai.*]`` bindings, each is injected at launch
as ``NERDIT_AI_<NAME>_URL/_KEY/_MODEL``, and the ``default`` binding also
sets ``OPENAI_BASE_URL/OPENAI_API_KEY/OPENAI_MODEL`` — point the app's
OpenAI SDK at these; no code change needed. WARNING: the ``secrets`` values you pass
here transit this agent's transcript in plaintext; for high-value keys
prefer ``nerdit secrets set`` from the CLI and deploy without ``secrets``.
Inputs: name (required), template_id (required), env, gpus, +8 more.
diagnose_projectA
Diagnose one service of an explicit project under the existing owner/admin policy.
Prefer an immutable project ID. The daemon resolves project membership and
reuses diagnose_service's failure bundle; this grants no additional authority.
Inputs: project (required), service, log_tail.
diagnose_serviceA
Use when: a service is failing and you need the reason, not the logs.
Bundles the deploy phase, crash forensics (``last_exit_code``,
``oom_killed``), a fresh health probe, AI-binding readiness, a bounded
log tail and a single ``remediation_code`` to branch on — call it after
``wait_for_service`` returns ``failed`` instead of scraping logs.
Owner-or-admin read: the bundle carries env/secret key *names* and app
log lines, never secret values.
Inputs: name (required), log_tail.
doctorA
Run the daemon's bounded environment health checks (docker/gpu/proxy/db/...).
Returns per-check ``{status, detail}`` plus a worst-of top-level
status. Every check is timeout-bounded server-side; details carry key
*names* only, never paths or secret values — safe for every role.
Inputs: no named parameters.
dump_databaseA
Capture a logical, application-consistent dump of a managed database.
The daemon runs the engine's own dump tool — ``pg_dump --format=custom``
for Postgres, ``redis-cli --rdb`` for Redis — from a throwaway container
built from the database's OWN image, against the running server. This is
the dump to take before a migration or a destructive change: unlike the
volume backup (``nerdit backup --volume``, no tool), it is consistent by
the engine's rules rather than by the filesystem's.
CUSTODY: the artifact is a server-side tar under the daemon's backups
directory holding **every row** of ``name``; it is never served over
HTTP and nothing but metadata comes back here — basename, size, sha256,
engine, format, duration. Treat the basename as the handle: it is what
``nerdit db restore`` takes.
RETENTION: the daemon keeps the last ``[retention].dump_keep_last``
dumps per database (default 5) and prunes older ones on its hourly
sweep, so a dump is not an archive. Copy one off the box if it must
outlive that window.
TIMEOUT: the default matches the usual MCP client read budget, not
the route's own 900: if your client gives up first, **a longer dump still completes
server-side and appears in ``list_database_dumps``**. So a read timeout
here is not a failure — call ``list_database_dumps`` and take the newest
entry. Do NOT blind-retry: this tool mints its own idempotency key per
call, so a retry is a second real dump (and the first one may still be
running, which answers ``409 dump.in_progress``).
Authorization is **owner-or-admin plus token scope**: a scoped submitter
can dump the databases it created, which is what makes this usable over
the (submitter-capped) cloud link. Refusals you should branch on: ``409
dump.database_not_ready`` (not running, or still doing initdb — poll
``list_databases`` for ``db_ready``), ``409 dump.in_progress`` (this
database already has one running; distinct from the daemon-wide
``backup.in_progress``), ``409 dump.too_many_in_flight``, ``409
dump.insufficient_disk`` (the error object carries top-level
``required_bytes`` / ``free_bytes``), ``422 dump.not_a_database``, and
``500 dump.failed``
whose ``hint`` is the tool's own last output line. There is deliberately
**no restore tool** — restoring replaces live data and stays on the CLI
(``nerdit db restore``) and REST.
Inputs: name (required), timeout_s.
get_ai_usageA
AI gateway usage per (UTC day, app, alias): requests, prompt and completion tokens, upstream errors. No cost estimate, no prompt trace.
Inputs: days, service.
get_app_configA
Read a deployed app's daemon-persisted config (deploy fields + ai bindings).
Secret values are never returned — only ``${secrets.X}`` refs and env
key names. Each ``[ai.<name>]`` binding shown here is injected into the
app at launch as ``NERDIT_AI_<NAME>_URL/_KEY/_MODEL``, and the
``default`` binding also sets ``OPENAI_BASE_URL/OPENAI_API_KEY/
OPENAI_MODEL`` (drop-in OpenAI SDK).
``deploy.release`` is the command run once inside the new image before
traffic moves (a failure aborts the deploy and reverts the image,
never the data — write idempotent migrations); ``deploy.cutover`` null =
zero-downtime swap when eligible, false = same-port swap. ``env_keys``
are runtime env names; secret refs are accepted only by
``ai.*.api_key``, ``db.*.password``, ``edge_auth.password``, a git
``token_ref`` and a whole-value app ``env`` entry
(``${secrets[.shared].KEY}`` / ``${vars[.shared].KEY}``) — a
``${secrets.shared.KEY}`` there resolves at launch for any owner, so a
human can place the secret and the agent only names it.
Inputs: name (required).
get_auditA
Read the audit log (admin-scoped), bounded to limit entries per page.
Returns an ``AuditLogPage`` dict. Non-admin tokens get a structured
``forbidden`` (403) error.
All filters compose with AND, and all are applied in SQL — narrowing is
cheap, so prefer a filter over paging.
Inputs: limit, since, until, action, +6 more.
get_configA
Read daemon config: one section view, or all sections when omitted.
Secret-bearing values are redacted server-side.
Inputs: section.
get_eventsA
Use when: you need the daemon's own account of what it just did.
The durable feed of autonomous transitions (``service.failed``,
``service.degraded``, ``service.deploy_succeeded``, ``model.ready``,
...), readable by any authenticated token. Two directions, and picking
the wrong one walks the wrong way through history.
Inputs: limit, types, cursor, service, +1 more.
get_guideA
Read one agent guide: how to build on this machine, for this daemon version.
Use when: before writing a ``nerdit.toml`` or deploying. Returns
``{topic, title, daemon_version, markdown}``: the exact keys, the order
of calls and the failure codes. Start with ``index``.
Inputs: topic (required).
get_projectA
The one-call picture of a project: read this before you deploy or diagnose.
Returns the project's services with their state, last deploy and
endpoint; the models and databases they reference with a readiness
flag (``null`` when readiness cannot be judged without a secret); every
public address under ``addresses``; and ``home``, the node it lives on
(always this node today). A name outside your scope is 403; an unknown
name is 404. Secret values never appear here.
Inputs: name (required).
get_serviceC
Get one service.
Inputs: name (required).
list_ai_budgetsA
List the monthly AI gateway token limits in force and this UTC month's use.
Returns ``{default_tokens_month, budgets: [{service, tokens_month,
used_tokens, month, state, own}]}``; ``state`` is ``ok``, ``warning``
(80 %) or ``exceeded`` (the gateway answers that app 429
``budget_exceeded`` until the UTC month turns). ``own: false`` means
the machine default alone applies. A non-admin sees its own apps only.
Inputs: no named parameters.
list_ai_provider_modelsA
List the model ids an OpenAI-compatible provider offers (submitter or admin).
The daemon calls ``GET {base_url}/models`` with the referenced shared
key, so you can pick a model for ``set_ai_route`` while the key stays on
the machine. Returns ``{base_url_host, models}`` (sorted ids only).
Read-only despite the POST underneath (no idempotency key).
Refusals: 422 ``ai_gateway.base_url_invalid`` / ``ai_gateway.secret_ref_invalid``,
503 ``secret_missing``, 502 ``ai_gateway.provider_unreachable`` /
``ai_gateway.provider_error`` (the HTTP status, never the provider's text).
Inputs: base_url (required), api_key_ref (required).
list_ai_routesA
List the machine AI gateway's aliases and whether the gateway is enabled.
Each alias shows its provider, provider model, base_url and the
``${secrets.shared.KEY}`` reference of its key: never a key value.
Inputs: no named parameters.
list_app_filesA
List an app's workspace: paths, sizes, sha256 and totals.
What this lists is exactly what ``deploy_app`` would build — the exclude
rules are enforced at write time, not at deploy time. Bounded at 500
files by construction, so there is no paging.
Inputs: name (required).
list_app_templatesA
List the app template store — deployable starter apps (id/name/coordinates).
Deploy one with ``deploy_template``. These are full app templates
(web/API/AI starters), not per-service presets.
Inputs: no named parameters.
list_database_dumpsA
List the dump tars this daemon holds for one managed database.
Newest first, ``{dump, size_bytes, created_at}`` per row, where
``created_at`` is the tar's mtime (the listing never opens an archive).
Metadata only, like ``dump_database``: the tars themselves stay under
the daemon's backups directory and are never served over HTTP, and each
one holds every row of ``name``.
Two things this read is for. It is the recovery path when a
``dump_database`` call outran your client's read budget — **the dump
still completes server-side and shows up here**, so list before you
retry. And it is how you check retention: the daemon keeps the last
``[retention].dump_keep_last`` per database (default 5) and prunes the
rest hourly, so on a default daemon what is listed here is all there is.
Retention can be turned off (``dump_keep_last = 0``), so the listing is
capped at the newest 500 instead: ``truncated`` is true when older tars
exist on the box that this page does not name.
Owner-or-admin plus token scope — the same gate as the dump that
produced them, because knowing which dumps a database has is knowing
something about the data.
Inputs: name (required).
list_databasesA
List managed databases (kind=database workloads), bounded to limit per page.
Returns a cursor-paginated page. A newly created database shows
``building`` until its off-tick image pull and readiness probe complete
(``db_ready`` true).
The ``endpoint`` is password-free by construction; lifecycle actions go
through the service tools.
Inputs: limit, cursor.
list_gpusA
List GPUs known to the daemon, with live utilization metrics.
Inputs: no named parameters.
list_guidesA
List this daemon's agent guides: {daemon_version, guides: [{topic, title, summary}]}.
Static text shipped with the daemon, the same for every caller. Read
``get_guide('index')`` first: it says which guide fits the request.
Inputs: no named parameters.
list_hooksA
List a deployed app's inbound webhooks (owner or admin only).
Returns ``{service_name, hooks: [{name, sender, path, header, prefix,
secret_ref, secret_key, url, created_at}]}``. ``url`` is null until the
machine is linked, and answers only once the app is shared.
Inputs: name (required).
list_modelsA
List served AI models (kind=model workloads), bounded to limit per page.
Returns a cursor-paginated page; pass ``cursor`` from the previous page
to continue. A newly served model shows ``building`` until its off-tick
pull completes; lifecycle actions go through the service tools.
Inputs: limit, cursor.
list_projectsA
List the projects this token can see, bounded to limit per page.
Each entry carries the project's services (state, endpoint) and every
advertised address. A scoped token sees only the projects its scope
names. Cursor-paginated; use ``get_project`` for the full picture of one.
Inputs: limit, cursor.
list_routesA
List the DB-authoritative route inventory, annotated with live Caddy state.
Models appear with ``route: null`` (loopback-only by design); each row
carries its live-table annotation.
Inputs: limit, cursor.
list_schedule_runsA
A schedule's runs, newest first (50 are kept).
Each run is ``{run_id, trigger, started_at, finished_at, outcome,
status_code}``. ``trigger``: ``cron`` | ``manual`` | ``catchup``.
``outcome``: ``running``, ``accepted`` (202), ``ok`` (other 2xx),
``failed`` (any other status), ``timeout``, ``unreachable`` (no
connection) or ``skipped_overlap``. The app's response body is never kept.
Inputs: name (required), schedule_name (required), limit.
list_schedulesA
List a deployed app's schedules (owner or admin only).
Returns ``{service_name, schedules: [{name, cron, path, timezone,
timeout_s, next_run_at, last_run}]}``. ``next_run_at`` is the next
occurrence within 8 days (UTC), null when none; a schedule fires only
while the app is running and healthy. ``last_run`` is the newest run
(``{run_id, trigger, started_at, finished_at, outcome, status_code}``).
Inputs: name (required).
list_secret_namesA
List a service's secret key names (values are never returned).
Inputs: service (required).
list_servicesB
List services (apps, models and databases), newest first.
Inputs: limit, cursor, status.
project_logsA
Read bounded logs of one service resolved within an explicit project.
Prefer the immutable project ID returned by list_projects. Membership is
resolved by the daemon; a same-name replacement cannot inherit a retired ID.
Existing node grants and local token roles still apply.
Inputs: project (required), grep, tail, since, +3 more.
proxy_statusA
Get the embedded proxy's typed state (TLS, apex, respawn, live routes).
Authenticated read: proxy state, TLS subjects + CA fingerprint, apex
registration, respawn backoff, and a tri-state live route table read
from the Caddy admin API. Complements ``list_routes`` (the
DB-authoritative inventory).
Inputs: no named parameters.
read_app_fileA
Read one file back from an app's workspace as text.
Use it before patching a file you did not write in this conversation, so
the next ``write_app_files`` replaces content you have actually seen.
Inputs: name (required), path (required).
redeploy_serviceA
Use when: a git app needs a new commit. Asynchronous — follow with wait_for_service.
Re-clones the repository and branch/tag the service was deployed from
and rebuilds it, so picking up a new commit is one call with the service
name alone. Use this instead of ``deploy_git`` when the service already
exists — every coordinate (repo, ref, subdir, private-repo credential
reference) is read back off the service. A service deployed from a
folder/zip has no recorded source and is refused. ``dry_run=True`` returns
the build/config plan diff (env key names only, values never). A
non-dry-run response carries
``summary``, ``hints`` (never empty) and ``next_step`` — the structured
follow-up call.
Inputs: name (required), dry_run, idempotency_key.
remove_ai_routeA
Remove a machine AI gateway alias (submitter or admin).
Refused with 409 ``ai_gateway.alias_in_use`` (naming the apps) while a
running app's ``[ai.*]`` uses it, unless ``force``.
Inputs: alias (required), force, idempotency_key.
remove_domainA
Remove a custom domain; its route disappears on the next reconcile tick. Idempotent.
Inputs: name (required), domain (required), idempotency_key.
remove_hookA
Remove an inbound webhook; its address stops answering. Idempotent.
The signing secret stays set (remove it with ``remove_secret``). A
webhook still declared in nerdit.toml comes back with a NEW address on
the next deploy.
Inputs: name (required), hook_name (required), idempotency_key.
remove_scheduleA
Remove a schedule and its run history. Idempotent (removed: false).
A schedule still declared in nerdit.toml comes back on the next deploy.
Inputs: name (required), schedule_name (required), idempotency_key.
remove_secretA
Delete one secret key, or all of a service's secrets when key is omitted.
Deleting a shared key can break every app still referencing it via
``${secrets.shared.KEY}``.
Inputs: service (required), key, idempotency_key.
remove_serviceB
Delete a service (teardown + remove).
Inputs: name (required), force, purge, idempotency_key.
resolve_variablesA
What a launch would see: per key, the winning scope and whether it is plain. No values.
The loop is "the agent asks, the human supplies". Call this before a
deploy to see which keys the service will receive (``scope`` is
``project`` or ``production/<service>``). When a key the app needs is
missing, do NOT invent or request the value in chat: ask the human to
run ``nerdit vars set <project> --secret --prompt KEY``, then call this
again to confirm the key is present. A secret value is never returned by
any tool. Owner or admin only; a name outside your scope is 403.
Inputs: project (required), service.
restart_daemonA
Restart the daemon to apply restart-required config (admin-scoped, audited).
Returns 202 with drain counts. **Over the HTTP MCP transport this kills
the connection serving this call**: a dropped response after issuing it
means the restart most likely started. Confirm with ``capabilities``
(``uptime_s`` resets); retrying with the same idempotency key answers
``409 daemon.restart_in_progress`` or a fresh 202, never a second
restart mid-drain.
Inputs: drain_timeout_s, idempotency_key.
restart_serviceB
Restart a service (clears backoff).
Inputs: name (required), idempotency_key.
run_commandA
Run a one-off command in a deployed service's image (migrations, seeds).
The command runs in a throwaway container built from the service's
current image with the same env, secrets, AI/DB bindings and named
volumes as the live container — the service itself keeps serving.
**Bounded-synchronous**: this call BLOCKS until the command exits or
``timeout_s`` seconds elapse, then returns ``{exit_code, timed_out,
oom_killed, duration_s, run_id, log_tail, ...}``. Branch on
``exit_code``/``timed_out`` — a non-zero exit is a normal 200 result,
not an error. One run at a time per service (409
``service.run_in_progress``).
Because the call blocks for minutes, **supply your own
``idempotency_key`` and REUSE it verbatim if you retry** — that is the
only thing standing between a client-side read timeout and a migration
running twice. A retried key REPLAYS an ``idempotent_replay`` envelope,
NOT the command's output — the run's stdout is deliberately never
cached at rest. That replay is an HTTP 200 carrying ``code:
"idempotent_replay"`` and NO ``exit_code``, so check for that code
before reading ``exit_code``. Re-run under a fresh key if you need the
output again, or read it from ``diagnose_service``'s ``last_run``.
**Key reuse protects a COMPLETED run only.** A failed call un-pins the
key, so a same-key retry really re-executes. In particular ``503
run.interrupted`` means the container started and was lost — the
command may have partially applied — and retrying it, with any key,
runs it again: stop and inspect instead. And if the daemon died
mid-run, the key stays claimed for 24 h and the retry returns ``409
idempotency_in_progress``; mint a fresh key once you have confirmed
the run is over.
Inputs: name (required), command (required), env, log_tail, +2 more.
run_scheduleA
Call a schedule's path now (a manual run); answers 202 at once.
Returns ``{run_id, outcome}``: ``running``, or ``skipped_overlap`` when
the previous run is still out. Read the result with
``list_schedule_runs``. Refusals: 404 ``schedule.not_found``, 409
``schedule.service_not_running`` (stopped, failed, degraded or
mid-cutover), 409 ``schedule.restart_required``.
Inputs: name (required), schedule_name (required), idempotency_key.
serveC
Register a service from a prebuilt image.
Inputs: name (required), image (required), env, gpus, +7 more.
serve_modelA
Serve a local AI model as an OpenAI-compatible endpoint.
Serving is asynchronous: the call returns immediately with the
model row in ``building`` while the daemon pulls the image and weights
off-tick; poll ``list_models`` (or ``get_service``) until it is
``running``. Lifecycle (stop / restart / delete) goes through the
existing service tools (``stop_service`` / ``restart_service`` /
``remove_service``).
An app connects to this model by declaring an ``[ai.<name>]`` binding
(provider ``ollama``, model = this model); at each launch it receives
``NERDIT_AI_<NAME>_URL/_KEY/_MODEL``, and the ``default`` binding also
sets ``OPENAI_BASE_URL/OPENAI_API_KEY/OPENAI_MODEL`` so an unmodified
OpenAI SDK reaches this endpoint with no code change.
Inputs: model (required), gpus, name, backend, +3 more.
service_logsA
Use when: you need the raw output a service or its build printed.
``source`` picks which output you get. **Pass ``source='runtime'`` when
you are debugging a running app** — the build and the app used to share
one stream, so a bare ``grep`` over a deployed app still matches
BuildKit layer chatter (``404B``, ``CACHED``, ``sha256:…``) from the
build that produced it. Lines written by an older daemon are stored as
stdout and therefore read as ``'runtime'`` whichever program printed
them.
``grep`` keeps only lines CONTAINING that text. It is a plain
**literal substring**, never a regex.
All three filters run server-side inside the ``tail`` bound, so ``tail``
counts matching lines: ``grep='Traceback', source='runtime', tail=20``
gives the last 20 app tracebacks out of a million-line log in one
bounded query. Prefer that over pulling a large tail and searching it
yourself.
Inputs: name (required), grep, tail, since, +2 more.
service_statsA
Get live CPU, memory, network and PID usage for a running service.
Returns ``{available, stats: {cpu_pct, mem_used_bytes, mem_limit_bytes,
mem_pct, net_rx_bytes, net_tx_bytes, pids}, gpus, cached}``.
**Branch on ``available``, never on zeroes.** ``available: false`` with
``stats: null`` is the normal answer when the service has no running
container or the daemon cannot reach Docker; every individual counter
is likewise ``null`` when unknown, so a missing metric never
masquerades as an idle one. ``cpu_pct`` follows the docker convention —
``100.0`` is one fully-used core, so a multi-core host can exceed 100.
For *why* a service is unhealthy use ``diagnose_service``; this tool
answers *how much* a healthy one is consuming. The daemon caches the
sample for 2 seconds, so polling it in a loop is cheap.
Inputs: name (required).
set_ai_budgetA
Set an app's monthly AI gateway token limit.
A submitter may only set a value at or below the limit in force (the
app's own, else the machine default) on apps it owns: raising or
removing a limit is for an admin or the console, 403
``ai_budget.raise_forbidden``. Not a spending guarantee: a
``provider = "api"`` binding or a key in a variable never crosses the
gateway. Refusals: 404 ``service.not_found``, 403 ``forbidden`` (not
your app).
Inputs: service (required), tokens_month (required), idempotency_key.
set_ai_routeA
Create or replace a machine AI gateway alias (submitter or admin).
Apps then declare ``[ai.default] provider = "gateway"`` and
``model = "<alias>"``: the daemon injects the gateway URL and a per-app
virtual key, and the provider key never enters a container. Answers
``enabled: false`` while ``[ai_gateway]`` is off (the alias is stored
and serves once it is enabled). Refusals: 422 ``ai_gateway.alias_invalid``,
``ai_gateway.base_url_invalid`` (not https, private address, userinfo),
``ai_gateway.secret_ref_invalid``.
Inputs: alias (required), model (required), base_url, provider, +2 more.
set_app_configA
Write an app's deploy or ai config section (admin/owner-scoped).
Writing the ``ai`` section re-wires the app's bindings: on the next
launch/restart each ``[ai.<name>]`` binding is injected as
``NERDIT_AI_<NAME>_URL/_KEY/_MODEL``, and the ``default`` binding also
sets ``OPENAI_BASE_URL/OPENAI_API_KEY/OPENAI_MODEL`` — pass
``restart=True`` to apply it immediately. A dry run needs neither an
``If-Match`` nor an idempotency key.
Inputs: name (required), values (required), section (required), dry_run, +3 more.
set_configB
Write a daemon config section (admin-scoped, validated, audited).
Inputs: values (required), section (required), dry_run, if_match, +1 more.
set_secretA
Set/merge write-only secrets for a service; returns key names only.
WARNING: the values you pass here transit this agent's transcript in
plaintext; for high-value shared keys (broadly-scoped API keys,
credentials shared across every app) prefer ``nerdit secrets set --shared`` from the CLI
instead of routing them through an agent. The leak-free path for any
value: a human runs ``nerdit secrets set <service> --prompt KEY``
(hidden input) and you only ever name ``KEY``; it is injected at
launch, overriding an ``env`` key of the same name. You may set secrets
before the service exists; the name is then reserved for your token
until you deploy it (another token's deploy of that name gets 409
``service.name_claimed``).
Inputs: values (required), service (required), idempotency_key.
set_variableA
Set/merge a project's variables; write-only unless secret=false. Returns names only.
WARNING: the values you pass here transit this agent's transcript in
plaintext, whether ``secret`` is omitted, ``true`` or ``false``. For any
credential, do not pass the value at all: ask the human to run
``nerdit vars set <project> --secret --prompt KEY`` (hidden input) and
only ever name ``KEY`` yourself. Use this tool for values that are fine
to appear in a transcript (a log level, a feature flag, a public URL).
A variable reaches a service's environment at launch. Precedence, lowest
to highest: the manifest ``env`` table, the project scope, the service
scope, then platform-injected bindings (``OPENAI_BASE_URL``,
``DATABASE_URL``…), which a variable can never override. Setting a key
again flips its plain/secret flag in that scope. Only the project's owner
or an admin may write (another token gets 403).
A running service picks the change up on its next restart or redeploy.
The machine-wide scope is not reachable here: use ``set_secret`` with
``shared``.
Inputs: values (required), project (required), secret, service, +1 more.
stop_serviceC
Stop a service (desired_state → stopped).
Inputs: name (required), idempotency_key.
system_diskA
Report disk usage: docker totals + named-volume/model/archive/backup trees.
Any authenticated read. Names and byte counts only (no absolute paths);
lists orphan images and orphan data dirs (reclaim them with
``system_gc``). Concurrent ``du`` walks run under a soft budget — an
overrun returns a partial body with a ``scan_timeout`` warning.
Inputs: no named parameters.
system_gcA
Garbage-collect orphan app images (admin-scoped, audited).
Reclaims ``nerdit-app/*`` image repos with no live workload row, verified
by re-listing so an in-use tag is reported skipped, never removed.
Inputs: dry_run, idempotency_key, include_orphan_data.
wait_for_serviceA
Use when: a deploy is in flight and you need its real outcome.
Blocks until the service converges (healthy) or fails, then returns
``{outcome: converged|failed|timeout|superseded, ...}`` — always, never
raising on a timeout. After ``stop_service``, ``converged`` means the
service is actually stopped.
On ``outcome: failed`` the response also carries ``diagnosis`` — the
FULL ``diagnose_service`` bundle (``remediation.code`` + ``detail``,
crash forensics, health probe, binding readiness and a bounded log
tail), folded in so a failure needs no second call. Branch on
``diagnosis.remediation.code``. It is ``null`` on every non-failed
outcome, and ``null`` on a failure your token is not owner-or-admin for
(the bundle carries app log lines) — in that case call
``diagnose_service`` yourself with a token that owns the app.
Inputs: name (required), timeout, version.
write_app_filesA
Write files into an app's server-side workspace, then deploy it.
The two-step idiom for building an app from this conversation:
``write_app_files`` (as many batches as you like) then ``deploy_app``.
The workspace survives the deploy and IS the working copy, so editing is
"write the one changed file → ``deploy_app`` again".
One batch is all-or-nothing: an invalid entry rejects the whole request
and nothing is written. Binary content is refused — deploy binaries from
a repo with ``deploy_git``; assets normally come from the build
(npm/pip). A secret belongs in ``set_secret``, which injects it at launch
without it ever living in a file. WARNING: file contents you pass here
transit this agent's transcript in plaintext; never write secrets into
app files.
SANDBOX: by DEFAULT containers run with all Linux capabilities dropped
(``cap_drop=["ALL"]``) and no-new-privileges — both are operator settings
(``[containers].drop_all_caps`` / ``[containers].no_new_privileges``), so
read the live profile in ``capabilities.sandbox`` rather than assuming: an
operator may have relaxed it. Under that default, an image whose entrypoint
does root work — ``chown``/``chmod`` of its own runtime dirs, dropping
privileges via ``setuid``/``setgid``, writing ``/var/run`` — dies before
your app ever starts. Stock ``nginx`` is the classic trap. Use a non-root
image and a non-root ``USER`` that owns the files it writes: for a static
site, ``nginxinc/nginx-unprivileged`` (listens on **8080**, so set
``port=8080``) or any tiny static server. A crash from this reports
remediation code ``image_needs_privileges`` in ``diagnose_service``. PORT
CONTRACT: the container MUST listen on the declared ``port`` (the tool
argument, else ``nerdit.toml`` ``[deploy].port``, else **8000**) — that is
the only port the daemon publishes and health-checks, so listening anywhere
else fails the health probe with a healthy-looking container. A port below
1024 is NOT the reason a root entrypoint is needed: every container runs on
the docker bridge in its own network namespace (never host networking),
where Docker sets ``net.ipv4.ip_unprivileged_port_start=0``, so binding 80
needs no capability and no root — the chown/setuid work does.
Inputs: name (required), files (required), delete, idempotency_key.
write_project_filesA
Write a project's source tree (its nerdit.toml included), then apply_project.
Exactly ``write_app_files`` on the workspace named after the project:
same all-or-nothing batch, same text-only rule, same caps, and
``list_app_files`` / ``read_app_file`` read it back under the project
name. One tree holds EVERY service; a service built from a subfolder
says so with ``build_settings.subdir``. The root ``nerdit.toml`` is the
declaration::
[project]
name = "asso"
[services.web]
port = 3000
[services.api]
port = 8000
build_settings = { subdir = "apps/api" }
[vars]
required = ["API_KEY"]
``[services.<name>]`` takes the ``[deploy]`` keys except ``name``: the
service ``web`` is served under the project name (``asso``), any other
under ``<service>--<project>`` (``api--asso``), and that label is the
name every other tool takes. ``[ai.*]`` / ``[db.*]`` bindings stay
top-level tables shared by every service; a declaration cannot create
a database (``create_database`` first, then bind it). WARNING: file
contents you pass here transit this agent's transcript in plaintext;
never write secrets into project files.
Inputs: files (required), project (required), delete, idempotency_key.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 76 tools
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.
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.
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.
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
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Hosted MCP server for live public-data APIs and Skills for AI agents.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceUnified deployment dashboard MCP server for AI agents. 9 tools to manage services across Vercel, Render, Railway, and Fly.io — deploy status, logs, service listing, environment variables, rollback, and health checks from one endpoint. Free tier: 50 requests/IP/day.3MIT
- AlicenseAqualityDmaintenanceMCP server for Emergent.sh that enables AI assistants to create, monitor, and interact with full-stack app projects, including responding to agent questions and taking preview screenshots.111MIT
- AlicenseAqualityCmaintenanceMCP server for the Partiri Cloud PaaS platform. Enables AI agents to manage workspaces, projects, services, deployments, and metrics.231MIT
- AlicenseNot gradedqualityCmaintenanceA remote MCP server that lets a coding agent turn a plain-language idea into a real, shareable product — creating the project and data model, serving live API endpoints, deploying custom endpoints and server-side functions, and reading request and function logs. It handles sign-up, OAuth-backed access, and OpenAPI spec generation so people can open, sign into, and use the app the agent builds.MIT