Single-Node k3s Quick Deploy

Install Neutree Agent Platform on a single-node k3s cluster — the quickest way to get the full platform running. The single-node profile matches the full one, just with a single PostgreSQL instance and an in-cluster NFS server for shared storage.

The same flow serves two kinds of nodes. Connected, every image is pulled from the public registry (ghcr.io / docker.io / registry.k8s.io). For a node with no internet access, the extra steps sit inline in collapsible Air-gapped blocks — expand one and they all stay open; that path installs from an image bundle via an in-cluster registry, so nothing is pulled from the internet.

Recommended spec: 8 vCPU / 32 GB / 200 GB disk — comfortable for roughly 10 concurrent workspaces. When you need HA or horizontal scale, use the production deployment, which also covers installing into an existing Kubernetes cluster.

One-line install (connected)

On a bare Linux machine with internet access, k3s is not required — the script installs it. Run as root:

curl -sfL https://docs.neutree.ai/nap/get.sh | sudo sh -

It installs k3s if missing, generates every secret, autodetects the node IP, creates a random admin password, and prints the login URL + credentials when it finishes. Configuration lands in /opt/nap/values.env; re-running the same line upgrades in place.

Common overrides:

# choose the host IP / admin password yourself
curl -sfL https://docs.neutree.ai/nap/get.sh \
  | sudo NAP_HOST=192.168.1.10 NAP_ADMIN_PASSWORD=your-password sh -

# generate values.env only — review/edit it, then re-run without the flag to install
curl -sfL https://docs.neutree.ai/nap/get.sh \
  | sudo sh -s -- --prepare-only

get.sh --help lists all flags (--version= to pin a release, --dir= to relocate the install dir). An air-gapped node can’t run the one-liner — follow the manual flow below.

Manual install

The same steps the one-liner automates, under your control — and the path for air-gapped nodes. Run everything on the node itself.

1. Get the materials

git clone https://github.com/neutree-ai/agent-platform
cd agent-platform/self-host

If you already ran the one-liner (even with --prepare-only), the same directory is at /opt/nap/self-host — work there instead.

Air-gappedbuild two bundles on a connected host, then stage them on the node

2. Prepare values.env

cp values.env.single-node.example values.env
./gen-secrets.sh        # fills random JWT / PG / TURN / SANDBOX secrets
vi values.env           # set NAP_HOST + ADMIN_PASSWORD

values.env.single-node.example already has single-node defaults baked in, so you only need to change two things:

• NAP_HOST — the node’s externally reachable IP; pods and the login entry both use it
• ADMIN_PASSWORD — the initial admin password

Everything else (PG replica count, storage classes, NFS backend) is preset for the single-node shape.

Air-gappedNAP_HOST must be set before the next step

3. Prepare the node (k3s)

The install needs a working k3s with its kubeconfig at /etc/rancher/k3s/k3s.yaml (the default). If the node doesn’t have k3s yet:

curl -sfL https://get.k3s.io | sh -

Air-gappedpreinstall.sh installs k3s and imports the images — no internet

4. Install

./install.sh --profile=single-node

install.sh first brings up the in-cluster NFS server (nap-nfs-server pod, backed by local-path), installs the CloudNativePG operator and the NFS subdir provisioner, renders and applies the manifests, then seeds the admin user, OAuth clients, and the MCP catalog. Connected, all images are pulled from the public registry.

Air-gappedthe image bundle switches install.sh to the in-cluster registry

5. Log in

http://<NAP_HOST>:30080
admin / <ADMIN_PASSWORD>

30080 is the NAP_NODE_PORT default baked into values.env.single-node.example.

Key differences from the standard deploy

Only the values that differ from the deployment guide defaults are listed; everything else carries over:

Field	Standard default	Single-node
DEPLOY_PROFILE	multi-node (implicit)	single-node
PG_INSTANCES	3	1
PG_STORAGE_CLASS	any RWO CSI	local-path
AGENT_STORAGE_CLASS	NFS / RWX CSI	local-path
NFS_SERVER / NFS_PATH	external NFS	in-cluster NFS pod (nap-nfs-server), computed by install.sh

All of these are already written into values.env.single-node.example, so you don’t fill them by hand.

NFS kernel modules must be enabled on the host

The in-cluster NFS uses the host kernel: the nap-nfs-server pod mounts nfsd on startup, and the nfs-subdir provisioner needs the nfs client module to mount. If the modules are missing, the nap-nfs-server pod won’t come up and the AFS PVC stays Pending.

Check whether they’re loaded:

lsmod | grep -E 'nfs|nfsd'

If there’s no output, load both manually:

sudo modprobe nfs
sudo modprobe nfsd
lsmod | grep -E 'nfs|nfsd'   # confirm loaded

If modprobe reports module not found, the kernel lacks the NFS module package — install it first (e.g. apt-get install linux-modules-extra-$(uname -r)) or switch to a kernel image with NFS support, then re-run the install.

Notes

• Data lives on the node — PVCs (including AFS shared files) use local-path, bound to the node’s disk. Back up externally if the data matters
• Run the installer on the node itself — the single-node profile pulls images into the local cluster
• Upgrades restart pods — expect a brief window while images roll. Connected: re-run the one-liner, or update the repo (git pull) and re-run ./install.sh --profile=single-node

Air-gappedupgrading an air-gapped node needs fresh bundles

What’s next

You’re logged in as the admin of a fresh, empty platform. Two short guides take you from here to a working agent:

1. Set up an API provider — connect a large-model API so agents can think. On a fresh install the provider list is empty; creating the first one takes a minute.
2. Your first agent — create a workspace and finish your first conversation, in under 5 minutes.

From there, concepts explains the moving parts, and the remaining guides cover triggers, multi-agent collaboration, and operating at scale.