A script's journey across the network

Imagine you just dispatched a job from the dashboard. Before you even finish your coffee, the script has traveled through five distinct systems. Click Next Step to trace the path.

Why nodes call home — not the other way around

Here's something clever: the Puppeteer server never pushes work to nodes. The nodes poll (repeatedly ask) for work. This is called the pull model, and it's a deliberate choice.

The four technologies that power this

Three programs, one system

Axiom is not one program — it's three that work together. Understanding who's who is the foundation for everything else.

The files that matter most

You don't need to memorize every file. But knowing where things live lets you tell your AI coding assistant exactly what to change.

How the server proves you're logged in

When you log in, the server creates a JWT (a digital ticket) and sends it to your browser. Every subsequent request includes that ticket. Here's the code that creates it:

def create_access_token(data: dict, expires_delta=None):
    to_encode = data.copy()
    if expires_delta:
        expire = datetime.now(UTC) + expires_delta
    else:
        expire = datetime.now(UTC) + timedelta(minutes=15)
    to_encode.update({"exp": expire})
    encoded_jwt = jwt.encode(
        to_encode, SECRET_KEY, algorithm=ALGORITHM
    )
    return encoded_jwt

The trust problem

Imagine you get a phone call from someone claiming to be from your bank. How do you know they're really from the bank? You need a shared secret — something only the real bank would know.

Same problem here. When a new machine connects and says "I'm a puppet node — give me work," how does the server know it's really yours and not a random intruder?

The JOIN_TOKEN — a hiring letter encoded as data

A new node gets a JOIN_TOKEN — a string you paste into the node's environment. It looks like random characters, but it's actually a Base64-encoded JSON document containing two things: the server's Root CA certificate, and a one-time enrollment token.

decoded_bytes = base64.b64decode(top_token)
decoded_str = decoded_bytes.decode('utf-8')
payload = json.loads(decoded_str, strict=False)

if "t" in payload and "ca" in payload:
    ca_content = payload["ca"]
    with open("secrets/root_ca.crt", "w") as f:
        f.write(ca_content)
    self.join_token = payload["t"]
    print(f"✅ Trust Bootstrapped")

From stranger to trusted worker in 4 steps

Why every script needs a signature

Nodes execute code that arrives over the network. If anyone could dispatch a job, an attacker could run anything on your machines. So the system requires every script to be signed with a private key whose public counterpart is registered in the system.

Here's the verification code that runs on the node before any script executes:

with open(self.verify_key_path, "rb") as f:
    public_key_bytes = f.read()
    public_key = serialization.load_pem_public_key(
        public_key_bytes
    )
sig_bytes = base64.b64decode(signature)
public_key.verify(sig_bytes, script.encode('utf-8'))
print(f"✅ Signature Verified for Job {guid}")

The polling loop — a node's heartbeat

Nodes poll the server every few seconds asking "any work for me?" Here's the code that does it, using the mTLS certificate for authentication:

async with httpx.AsyncClient(
    verify=VERIFY_SSL,
    cert=(self.cert_file, self.key_file)
) as client:
    headers = {
        "X-Node-ID": self.node_id,
        "X-Node-Secret-Hash": secret_hash,
    }
    resp = await client.post(
        f"{AGENT_URL}/work/pull",
        headers=headers,
        timeout=10.0
    )
    if resp.status_code == 200:
        data = resp.json()
        if data: return data

The full conversation — watch it happen

Here's the complete exchange between all the components when you dispatch a job. Click Next Message to see each step.

Test your understanding

Three security problems need three different solutions

Think of a high-security venue with three different checkpoints — not because they're paranoid, but because each checkpoint catches a different kind of threat.

All three checks in one route

The POST /work/pull endpoint that nodes call is a perfect example. It enforces multiple checks in a single line:

@app.post("/work/pull", response_model=PollResponse)
async def pull_work(
    request: Request,
    node_id: str = Depends(verify_node_secret),
    api_key: str = Depends(verify_api_key),
    db: AsyncSession = Depends(get_db)
):
    r = await db.execute(
        select(Node).where(Node.node_id == node_id)
    )
    n = r.scalar_one_or_none()
    if n and n.status == "REVOKED":
        raise HTTPException(status_code=403)

Secrets stored in the database are encrypted

Jobs can carry secrets (like API keys) that get injected as environment variables during execution. These are stored encrypted in the database using Fernet encryption.

Security in practice

The full picture — click to explore

When something breaks — where to look

Final challenge — put it all together