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

go install github.com/PointOfData/podos-cli/cmd/podos@latest

This installs the podos binary into $(go env GOPATH)/bin. 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.

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 — --gateway (mygw.pod-os.com) and --actor (<actor>@mygw.pod-os.com) are routing identities used inside the message envelope. They are not DNS names and cannot be dialed.

Dial the Gateway load balancer, address the Actor. podos can auto-discover the load-balancer IP, so you usually pass only --actor.

Command recipes

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

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

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

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

# Skip discovery by dialing an explicit socket:
podos get --actor test@mygw.pod-os.com --unique-id demo1 --host <lb-ip> --port 62312

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 that matches the verified shape—not a guess.

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.pod-os.com --unique-id it-1 --tag k=v
podos get   --actor test@mygw.pod-os.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.pod-os.com --intent GetEventsForTags --data "health_check=test"

# Once RespondToHealthChecks is live, the status probe returns Status:
podos send --actor mysocket@mygw.pod-os.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.

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