Connect internal network nodes (SpartanX NodeX PoP) to enable scanning of private infrastructure and internal network segments. This guide covers how to bring a SpartanX Connector Node online: import the image, put it on the right network, log in, and pair it with the SpartanX platform. After pairing, the node exposes its local network segment to the platform for scanning.

You need two things from whoever built the image:

1. The node image — OVA / VMDK / VHDX / QCOW2. Ask the AI agent for the current download link and pick the format for your hypervisor.

2. The first-login credentials for the spartanx user (see callout below).

Credentials — read before you start

Only used for the initial setup of a new internal node. Once the node is provisioned and you log in for the first time, change the password on the installed machine and use that new password from then on.

The default user and first-login password are rotated on every build and are not embedded in the image.

Always ask the AI agent inside the SpartanX platform for the current default user and password before you start a new setup.

If you download a new image, ask the AI agent again — credentials from a previous build will not work on a freshly built image.

1. Import the image

Pick the format for your hypervisor. The OVA carries a baked hardware envelope (4 vCPU / 8 GB RAM). The raw disk formats (VMDK / VHDX / QCOW2) carry no hardware config, so you set CPU / RAM yourself when you create the VM — use at least 4 vCPU / 8 GB.

For GCP / AWS / Kubernetes, skip this and see “Cloud & Kubernetes” below.

VirtualBox (.ova) — File ▸ Import Appliance…, select the .ova, accept the baked defaults (4 vCPU / 8 GB RAM; raise them for heavy scans), and import.

VMware Workstation / Fusion / Player (.ova) — File ▸ Open…, select the .ova, name the VM and choose a storage path, then click Import (accept the OVF-spec warning if one appears).

VMware ESXi / vSphere (.ova) — in the vSphere / Host Client: Create / Register VM ▸ Deploy a virtual machine from an OVF or OVA file, upload the .ova, pick the datastore and a bridged port group, and finish.

CLI: ovftool spartanx-node-<version>.ova vi://<esxi-host>.

Hyper-V (.vhdx) — Hyper-V Manager ▸ New ▸ Virtual Machine:

1. Generation 1 — the image is BIOS; a Gen 2 (UEFI) VM will not boot.

2. Startup memory ≥ 4096 MB.

3. Networking — connect to an External virtual switch (see step 2).

4. Use an existing virtual hard disk and select the .vhdx. Finish.

5. In the VM’s Settings ▸ Processors, set virtual processors to ≥ 4.

KVM / QEMU (virt-manager) (.qcow2) — New VM ▸ Import existing disk image, select the .qcow2, set memory / CPU (≥ 8 GB / 4 vCPU), keep firmware on BIOS, and attach the NIC to a bridge (e.g. br0), not the default NAT network.

Proxmox VE (.qcow2) — create a VM with no disk, then import and attach the disk:

qm importdisk <vmid> spartanx-node-<version>.qcow2 <storage>

Attach the imported disk to the VM, set it first in Boot Order, leave the firmware on SeaBIOS (default), put the NIC on a bridge (vmbr0), and boot.

2. Set the network mode

A connector node must reach two networks at once:

Outbound internet — to reach the SpartanX platform (pairing, heartbeat, tunnel).
The private segment you want to scan — e.g. 192.168.0.0/24.

Use a Bridged Adapter, not NAT. Bridged puts the VM directly on your physical LAN, so it gets an IP on the target segment and routes to the internet through your LAN gateway. NAT would give internet access but hide the node behind the host, so it could not reach the local segment as a peer.

VirtualBox — Settings ▸ Network ▸ Adapter 1 ▸ Attached to: Bridged Adapter, then pick the physical NIC on the segment to scan.
VMware — set the adapter to Bridged (replicate physical network state).
Hyper-V — connect the adapter to an External virtual switch bound to the physical NIC (Virtual Switch Manager ▸ New ▸ External).
KVM / libvirt — attach the NIC to a bridge (e.g. br0), not the default NAT network (virbr0).
Proxmox — put the NIC on a Linux bridge (vmbr0) bridged to the physical NIC.

Cloud VMs (GCP / AWS) reach the internet by default; make sure the instance also has a route / interface onto the private segment you want to scan.

Outbound endpoints — allow these through any corporate firewall (HTTPS/TLS on 443, tunnel on 443/8443):

Host	Purpose
api.spartanx.ai	Pairing handshake
nodes.spartanx.ai	Heartbeat + node control plane (mTLS)
relay.spartanx.ai	Tunnel transport (WSS)

3. Boot and log in

Boot the VM. On first boot a one-shot service locks the public Kali account, so the only way in is the spartanx user.

Get the latest credentials first. Before logging in, request the current default user and first-login password from the AI agent inside the SpartanX platform. These credentials are for the initial setup of a new internal node only and rotate on every build, so always ask for the latest values rather than reusing credentials from a previous node. If you downloaded a new image, ask the AI agent again — older credentials will not work.

After your first successful login, change the password on the installed machine and use that new password for all subsequent access to this node.

ssh <default-user>@<node-ip>

Use the first-login password provided by the AI agent.
The first login forces a password change (PAM). Enter the build password, then set a new one. This is expected.

Find <node-ip> from your DHCP server, your router’s client list, or by running ip a on the console.

4. Get a pairing code from the dashboard

In the SpartanX platform:

1. Go to Red Teaming ▸ Connector Nodes ▸ Add Node.

2. Fill the form:

Node Name — a descriptive label (e.g. HQ_DataCenter_Segment).
Description — optional.
Network Segments (CIDR) — the segment this node provides access to (e.g. 192.168.0.0/24). Press Enter or click + to add each one.

3. Click Register Node. The node appears as Pairing in Progress.

4. In the Pairing Token panel, enter a reason for revealing the token (min 10 chars — recorded for audit), then click Reveal pairing token.

5. Copy the token now — it looks like sxn_pair_…. It is single-use by the agent: once the node finishes pairing it cannot be revealed again. While the node is still pairing you can re-reveal it with a new justification.

5. Run the pairing command on the node

The pairing command must run as root. On the node:

sudo -i        # root shell (you'll be prompted for the spartanx password)

spartanx-pair sxn_pair_<your_token>

On a production node against api.spartanx.ai the defaults are correct — no environment variables are needed. The control-plane endpoint is learned automatically from the pairing response.

A successful run prints all seven steps and ends with:

Pairing complete!
  Node ID:  <uuid>
  Proxy:    Phalanx transparent proxy active
  Status:   Connecting to relay...

It enables and starts three services: phalanx, jupyter-kg, and spartanx-agent.

6. Verify

On the node:

systemctl status spartanx-agent phalanx
journalctl -u spartanx-agent -f

A healthy agent logs tunnel connected to relay and a heartbeat every 30 s with no rejections.

In the dashboard the node flips from Pairing in Progress to Connected, shows a recent Last seen, and reports its agent version as Up to date.

Cloud & Kubernetes (GCP / AWS / Kubernetes)

The node also ships as a GCP GCE image, an AWS AMI, and an OCI container image for Kubernetes. These are not public downloads — access is granted per build.

Request access first

Ask the AI agent inside the SpartanX platform for connector-node image access, and send the identifier for your platform. We grant read access to that identity — we do not need any credential from you.

Platform	What you send us	What we grant
GCP (GCE image)	The email of the IAM principal that will launch the VM — a service account (preferred), e.g. [email protected], or a Google user account.	roles/compute.imageUser on the image for that principal.
AWS (AMI)	Your 12-digit AWS account ID + the region you will launch in.	Your account added to the AMI’s launch permissions (we copy the AMI into your region if needed); we reply with the AMI ID.
Kubernetes (Artifact Registry)	The email of the GCP service account your cluster pulls with — on GKE the node pool SA or a Workload-Identity SA; on EKS / on-prem a GCP SA for your imagePullSecret.	roles/artifactregistry.reader on the image repository for that service account.

A bare GCP project ID is not enough — GCP IAM grants access to principals (service accounts / users), not to projects.

GCP — launch and pair

gcloud compute instances create spartanx-node \
  --project=YOUR_PROJECT --zone=YOUR_ZONE \
  --image-project=spartanx-public-images \
  --image=spartanx-node-<version> \
  --machine-type=e2-standard-4

The identity running this command must be the principal we granted compute.imageUser. Then SSH into the instance and pair exactly as in steps 3 and 5. Give the instance a route or interface onto the private segment you want to scan.

AWS — launch and pair

aws ec2 run-instances --region YOUR_REGION \
  --image-id ami-XXXXXXXXXXXX \        # the AMI ID we send you
  --instance-type t3.xlarge \
  --key-name YOUR_KEY --subnet-id subnet-XXXXXXXX

SSH in as spartanx and pair as in steps 3 and 5. Place the instance on a subnet that can reach the segment you want to scan.

Kubernetes — deploy and pair

The pull identity must already have artifactregistry.reader (see the table above). The container needs NET_ADMIN + NET_RAW for the transparent proxy and must be able to reach the segment you want to scan (commonly hostNetwork: true).

apiVersion: apps/v1
kind: Deployment
metadata:
  name: spartanx-node
spec:
  replicas: 1
  selector:
    matchLabels: { app: spartanx-node }
  template:
    metadata:
      labels: { app: spartanx-node }
    spec:
      hostNetwork: true
      containers:
        - name: spartanx-node
          image: gcr.io/spartanx-public-images/nodex:<version>
          securityContext:
            capabilities:
              add: ["NET_ADMIN", "NET_RAW"]

On GKE the node pool’s service account (granted artifactregistry.reader) pulls directly. On EKS / on-prem, create an imagePullSecret from your puller service account and add imagePullSecrets to the pod spec. Pair by exec-ing into the pod:

kubectl exec -it deploy/spartanx-node -- spartanx-pair sxn_pair_<token>

Troubleshooting

Symptom	Likely cause / fix
First-login password rejected	Credentials rotate on every build and are only valid for the initial setup. Ask the AI agent for the latest default user and password. If you already changed the password on the machine, use that one.
Dashboard stays Pairing in Progress	The pairing command was not run, or it errored before completing. Re-check the node console output.
spartanx-pair: must run as root	Run it under sudo -i (or sudo -E with the env vars inline).
[4/7] … Error: pairing failed	The platform rejected the handshake. Confirm the token is correct and still Awaiting agent pairing, and that the node can reach api.spartanx.ai.
Agent up, but heartbeat rejected by server status=403	The agent is hitting the public API endpoint instead of the mTLS control-plane gateway. Production learns it automatically from the pairing response — re-pair to refresh it.
Heartbeat tls: certificate signed by unknown authority	Outdated agent — the control-plane gateway serves a public (Let's Encrypt) cert. Rebuild the node from a current image.
Node version shows Blocked	The agent build is too old / not advertising a version the platform accepts. Rebuild from a current image.
Can't reach the target segment	Network adapter is on NAT or the wrong physical NIC. Switch to Bridged on the NIC on the segment (step 2).

Internal Connector Node(s) - Setup & Pairing Guide for NodeX