Quick Start

Let's walk through the basic workflow: connecting a node, discovering an agent, running recon, and executing an operation.

Prerequisites

You should have:

  • Praxis service running (via Docker or native build)
  • At least one LLM configured (see Configuration)
  • A node running on a system with an AI agent installed
  • The praxis TUI installed (see Installation)

Step 1: Check Your Node

Launch the TUI:

praxis

Open the Nodes window with Ctrl+L. You should see your node in the node list. Use ↑/↓ to select it, then press Enter or → to focus the agent pane. The detail pane shows:

  • Machine name and OS details
  • Detected agents — which AI assistants were found
  • Status of interception, sessions, etc.

If no agents show up, make sure the target system actually has Claude Code, Codex CLI, Gemini CLI, or another supported agent installed and configured.

Step 2: Select an Agent

In the agent pane, use ↑/↓ to select an agent. This focuses all subsequent recon and session actions on that agent.

Step 3: Run Reconnaissance

With an agent selected, press r to open the Recon overlay. This performs static reconnaissance:

  • Discovers MCP servers and other tool integrations
  • Lists configuration files and their contents
  • Shows session history — past conversations and their locations
  • Enumerates project paths where the agent has been used

Switch tabs with Tab (or 1 2 3) to browse Config, Tools, and Sessions. Press r to refresh static recon.

Semantic Recon

For deeper discovery, press Ctrl+U to run semantic recon (requires an LLM configured for "Semantic Parser"). This uses the LLM to parse configuration files and extract tool definitions that might not be obvious from static analysis. It also creates sessions and communicates directly with the agent to discover its full capabilities, so it takes longer than static recon.

Step 4: Look Around

With recon data, you can:

View configuration files — In the Config tab, pick any file to see its contents.

Browse sessions — In the Sessions tab, see what conversations the agent has had and which projects it's worked on.

Check tools — In the Tools tab, see what MCP servers, skills, or plugins are available to the agent.

Step 5: Create a Session

In the Nodes window, with an agent selected, press Enter to open the session options. You can specify a working directory and toggle YOLO mode; press Enter again to start the chat. See Sessions for the session lifecycle and Terminal UI for the complete chat controls.

Working Directory — where the agent should operate. Affects what files it can see and work with.

YOLO Mode — when enabled, the agent auto-approves all tool calls without asking for confirmation. Use this for automation, but be careful — it will execute whatever the agent decides to run.

Once the session is created, send prompts directly from the chat view.

Step 6: Run an Operation

Operations are predefined tasks you can execute through agents. The Operations window (Ctrl+P) has a third tab, Triggers, for automating when chains fire (see Semantic Operations); this walkthrough only uses Library and Executions. The library starts empty, so let's create a simple one first.

Create Your First Operation

  1. Open the Operations window (Ctrl+P) and switch to the Library tab
  2. Press Ctrl+N to create a new operation
  3. Fill in:
    • Name: hello-world
    • Short Name: hello-world — this (not Name) is what builds the category::short_name reference used to run the operation later, and saving is blocked until it's set
    • Category: test
    • Description: A simple test operation
    • Prompt: Say hello and tell me what directory you're currently in.
    • Mode: one-shot
    • Timeout: 60
    • YOLO: leave off (toggle on later to auto-approve tool calls for this operation)
  4. Save the form with Ctrl+S

Run It

  1. In Library, select test::hello-world and press Ctrl+R
  2. Choose your node and agent
  3. Confirm the operation reference test::hello-world

The operation executes through your agent. Watch the output in real-time in the Executions tab — you'll see the agent's response appear as it completes.

Operation Modes

  • One-shot - sends the prompt directly to the agent and returns the response
  • Agent - uses an orchestrating LLM to run multi-turn interactions with the target agent (useful for complex tasks)

For more complex workflows, you can chain multiple operations together. See Semantic Operations for details.

Step 7: Enable Interception (Optional)

To see the traffic between the agent and its LLM backend:

Privilege required: The node must run as root on Linux or as an elevated administrator on Windows before interception can be enabled.

  1. In the Nodes window (Ctrl+L), select your node
  2. Press i and confirm — the TUI auto-picks the method by node OS (TPROXY on Linux, VPN on Windows); macOS and other platforms aren't supported

Praxis supports four interception methods in total — Proxy (system proxy settings), VPN (TUN adapter for packet-level routing), Hosts (hosts file), and TPROXY (kernel-level redirection, the default/recommended method on Linux) — but the TUI's auto-pick only ever chooses TPROXY or VPN. To set a method explicitly (e.g. Proxy or Hosts), use the non-interactive CLI instead: praxis intercept enable <node-prefix> --method <proxy|vpn|hosts|tproxy>.

Open the Intercept window (Ctrl+T) to watch captured traffic in the Traffic tab. You can see:

  • Full request/response bodies
  • Prompts and completions
  • Tool calls and results

See Interception for setup and scope, and Terminal UI for traffic-view controls.

What's Next?