Documentation

Learn the concepts and tools behind Pod-OS

Testing Code Paths with podos

podos is a command-line client for the Actor Network. It speaks the same message protocol as your code, so you can exercise real Gateways and Actors from a terminal—before, during, and after you write the code that does the same thing. Pairing podos with a coding agent (such as Cursor) turns "I think this message is right" into "I verified this message against a live Actor."

The golden rule: verify behavior against a running Actor Network first, then write code against reality. Message formats and Intent requirements are easy to get wrong from memory; a live probe removes the guesswork.

Install

cargo install --git https://github.com/PointOfData/podos-cli --tag v0.1.0

This installs the podos binary into ~/.cargo/bin. Make sure that directory is on your PATH. Output is structured JSON (status, message, event id/unique id, tags, payload), which makes it easy for a coding agent to parse and act on.

For the latest from main, omit --tag. See the podos-cli repository for details.

Two addressing layers (do not conflate)

  • Socket layer — --host / --port is the TCP dial target (a Gateway load balancer, e.g. <gateway>-lb:62312). It is not a routing identity.
  • Message layer — --connection-gateway is the gateway FQN you dialed (registration identity for envelope From). --actor (<actor>@<its-gateway>.<domain>) is the routing target. These are not DNS dial targets.

Dial the gateway TCP endpoint, address the actor. On a hosted gateway use explicit --host and --connection-gateway (from the dashboard Connection Info modal).

Hosted gateway example

export PODOS_GATEWAY_HOST=k8s-example-zerothlb-....elb.us-west-2.amazonaws.com
export PODOS_GATEWAY_PORT=62312
export PODOS_GATEWAY_FQN=zeroth.example.com   # connection gateway you dialed

podos get \
  --host "$PODOS_GATEWAY_HOST" --port "$PODOS_GATEWAY_PORT" \
  --connection-gateway "$PODOS_GATEWAY_FQN" \
  --actor Foobar@zeroth.example.com \
  --unique-id demo1 --data --tags

You may connect to any gateway you are permitted to use; set --connection-gateway to that gateway's FQN, not necessarily a name containing zeroth.

Command recipes

# Store an event with a tag
podos store --actor test@mygw.example.com --unique-id demo1 --type "demo" --tag foo=bar

# Read it back
podos get --actor test@mygw.example.com --unique-id demo1 --data --tags

# Search by tag (mirrors GetEventsForTags in code)
podos search --actor actor_registry@mygw.example.com --tag actor_type=gateway

# Send a specific Intent
podos send --actor test@mygw.example.com --intent GetEvent --unique-id demo1 --data

# Explicit socket (local kind or hosted NLB):
podos get --actor test@mygw.example.com --unique-id demo1 \
  --host <lb-host> --port 62312 --connection-gateway mygw.example.com

Handshake OK but request times out?

If GatewayId succeeds and a later Intent waits until timeout with no error, the gateway likely could not route the reply back to your registered client. Check:

  • ClientName is unique per TCP connection
  • From = <ClientName>@<connection-gateway-FQN> (same gateway you dialed)
  • This is not an Auth0 or dashboard login issue; user_name / passcode are optional unless your gateway requires them

Using podos across the development lifecycle

1. During development (exploration)

Before writing a handler that stores, links, or queries data, drive the same Intent with podos and inspect the JSON response. Confirm which fields are required, how tags come back, and what a real error looks like. Then have your coding agent write code against the verified shape—not a guess.

On a Get or search that includes links, each adjacency row is the object you asked for toward its neighbor: source_unique_id, target_unique_id, and one strength. Map that JSON onto Linked. strength_a and strength_b appear on store and LinkEvent writes (LinkFields). See Query data.

A productive loop with a coding agent:

  1. Ask the agent to propose the podos command for the behavior you want.
  2. Run it against a running Actor Network and capture the JSON.
  3. Feed the response back to the agent so it writes code against the real contract.

2. Unit testing (validate before you send)

The SDK can validate a message before it is encoded and sent, and it produces structured, machine-readable errors that a coding agent can act on directly. Gate this behind an environment variable in tests:

// In application/test code, gated by PODOS_VALIDATE=1
if err := msg.Validate(); err != nil {
    // err carries struct_path, wire_field, rule, fix, and example_code
    t.Fatalf("invalid message: %v", err)
}

podos itself enables validation by default: if a message is invalid it is not sent, and the JSON result includes a validation array with struct_path, wire_field, rule, fix, and example_code. This makes podos a fast, dependency-free way to unit-test message construction—run the command, read the correction, fix the code, and repeat.

3. Integration testing (live round-trips)

For end-to-end confidence, run real round-trips against a running Actor Network and assert on the JSON:

# Store, then read back and confirm the tag survived the round-trip
podos store --actor test@mygw.example.com --unique-id it-1 --tag k=v
podos get   --actor test@mygw.example.com --unique-id it-1 --tags

Use a dedicated scratch/test Actor for write experiments so you never pollute real data. A coding agent can script these steps, diff the actual JSON against expectations, and report mismatches.

Health-checking a Socket Actor

When you build a Socket Actor, podos confirms it is genuinely healthy—not just accepting TCP:

# A Socket (non-Neural-Memory) Actor should NOT answer NM queries:
podos send --actor mysocket@mygw.example.com --intent GetEventsForTags --data "health_check=test"

# Once RespondToHealthChecks is live, the status probe returns Status:
podos send --actor mysocket@mygw.example.com --intent StatusRequest

Safety

  • Point podos at a local or development Actor Network. Reaching any non-local context should require an explicit opt-in flag.
  • Never run write Intents (store/link) against production while exploring.
  • Use a scratch/test Actor for round-trip experiments.
  • Use the Gateway load-balancer socket directly; the binary handshake does not survive kubectl port-forward.

Previous: SDKs and APIs — language clients that speak the same protocol as podos.

Next: SDK Knowledge Prompts — feed authoritative Pod-OS reference material to your coding agent so it designs and implements against the real protocol.